From 6b62d2cd688c13facd07a6e846b5934a5e8f3c37 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Thu, 9 Aug 2018 16:21:26 -0700 Subject: [PATCH 01/13] remove SQL Server Books Online (#6916) --- ...onfiguring-parameters-and-parameter-data-types.md | 4 ++-- docs/framework/data/adonet/connection-events.md | 2 +- .../data/adonet/connection-string-syntax.md | 2 +- docs/framework/data/adonet/local-transactions.md | 2 +- .../data/adonet/sql-server-data-type-mappings.md | 5 +++-- .../data/adonet/sql/authentication-in-sql-server.md | 2 +- .../authorization-and-permissions-in-sql-server.md | 2 +- .../data/adonet/sql/clr-stored-procedures.md | 12 ++++++------ docs/framework/data/adonet/sql/clr-triggers.md | 6 +++--- .../data/adonet/sql/clr-user-defined-types.md | 12 ++++++------ .../comparing-guid-and-uniqueidentifier-values.md | 7 ++++--- .../sql/creating-application-roles-in-sql-server.md | 2 +- ...g-permissions-with-impersonation-in-sql-server.md | 8 -------- .../data/adonet/sql/data-encryption-in-sql-server.md | 8 ++++---- .../adonet/sql/database-mirroring-in-sql-server.md | 4 ++-- 15 files changed, 36 insertions(+), 42 deletions(-) diff --git a/docs/framework/data/adonet/configuring-parameters-and-parameter-data-types.md b/docs/framework/data/adonet/configuring-parameters-and-parameter-data-types.md index eb6d63507b897..db9c02a4b35ec 100644 --- a/docs/framework/data/adonet/configuring-parameters-and-parameter-data-types.md +++ b/docs/framework/data/adonet/configuring-parameters-and-parameter-data-types.md @@ -9,7 +9,7 @@ ms.assetid: 537d8a2c-d40b-4000-83eb-bc1fcc93f707 # Configuring Parameters and Parameter Data Types Command objects use parameters to pass values to SQL statements or stored procedures, providing type checking and validation. Unlike command text, parameter input is treated as a literal value, not as executable code. This helps guard against "SQL injection" attacks, in which an attacker inserts a command that compromises security on the server into an SQL statement. - Parameterized commands can also improve query execution performance, because they help the database server accurately match the incoming command with a proper cached query plan. For more information, see [Execution Plan Caching and Reuse](http://go.microsoft.com/fwlink/?LinkId=120424) and [Parameters and Execution Plan Reuse](http://go.microsoft.com/fwlink/?LinkId=120423) in SQL Server Books Online. In addition to the security and performance benefits, parameterized commands provide a convenient method for organizing values passed to a data source. + Parameterized commands can also improve query execution performance, because they help the database server accurately match the incoming command with a proper cached query plan. For more information, see [Execution Plan Caching and Reuse](/sql/relational-databases/query-processing-architecture-guide#execution-plan-caching-and-reuse) and [Parameters and Execution Plan Reuse](/sql/relational-databases/query-processing-architecture-guide#PlanReuse). In addition to the security and performance benefits, parameterized commands provide a convenient method for organizing values passed to a data source. A object can be created by using its constructor, or by adding it to the by calling the `Add` method of the collection. The `Add` method will take as input either constructor arguments or an existing parameter object, depending on the data provider. @@ -87,7 +87,7 @@ Command objects use parameters to pass values to SQL statements or stored proced Stored procedures offer many advantages in data-driven applications. By using stored procedures, database operations can be encapsulated in a single command, optimized for best performance, and enhanced with additional security. Although a stored procedure can be called by passing the stored procedure name followed by parameter arguments as an SQL statement, by using the collection of the [!INCLUDE[vstecado](../../../../includes/vstecado-md.md)] object enables you to more explicitly define stored procedure parameters, and to access output parameters and return values. > [!NOTE] -> Parameterized statements are executed on the server by using `sp_executesql,` which allows for query plan reuse. Local cursors or variables in the `sp_executesql` batch are not visible to the batch that calls `sp_executesql`. Changes in database context last only to the end of the `sp_executesql` statement. For more information, see SQL Server Books Online. +> Parameterized statements are executed on the server by using `sp_executesql,` which allows for query plan reuse. Local cursors or variables in the `sp_executesql` batch are not visible to the batch that calls `sp_executesql`. Changes in database context last only to the end of the `sp_executesql` statement. For more information, see [sp_executesql (Transact-SQL)](/sql/relational-databases/system-stored-procedures/sp-executesql-transact-sql). When using parameters with a to execute a SQL Server stored procedure, the names of the parameters added to the collection must match the names of the parameter markers in the stored procedure. The [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to an SQL statement or a stored procedure. It treats parameters in the stored procedure as named parameters and searches for matching parameter markers. For example, the `CustOrderHist` stored procedure is defined by using a parameter named `@CustomerID`. When your code executes the stored procedure, it must also use a parameter named `@CustomerID`. diff --git a/docs/framework/data/adonet/connection-events.md b/docs/framework/data/adonet/connection-events.md index 8ecbc770ec266..fbc9c2854b230 100644 --- a/docs/framework/data/adonet/connection-events.md +++ b/docs/framework/data/adonet/connection-events.md @@ -15,7 +15,7 @@ All of the .NET Framework data providers have **Connection** objects with two ev |**StateChange**|Occurs when the state of the **Connection** changes.| ## Working with the InfoMessage Event - You can retrieve warnings and informational messages from a SQL Server data source using the event of the object. Errors returned from the data source with a severity level of 11 through 16 cause an exception to be thrown. However, the event can be used to obtain messages from the data source that are not associated with an error. In the case of Microsoft SQL Server, any error with a severity of 10 or less is considered to be an informational message, and can be captured by using the event. For more information, see the "Error Message Severity Levels" topic in SQL Server Books Online. + You can retrieve warnings and informational messages from a SQL Server data source using the event of the object. Errors returned from the data source with a severity level of 11 through 16 cause an exception to be thrown. However, the event can be used to obtain messages from the data source that are not associated with an error. In the case of Microsoft SQL Server, any error with a severity of 10 or less is considered to be an informational message, and can be captured by using the event. For more information, see the [Database Engine Error Severities](/sql/relational-databases/errors-events/database-engine-error-severities) article. The event receives an object containing, in its **Errors** property, a collection of the messages from the data source. You can query the **Error** objects in this collection for the error number and message text, as well as the source of the error. The .NET Framework Data Provider for SQL Server also includes detail about the database, stored procedure, and line number that the message came from. diff --git a/docs/framework/data/adonet/connection-string-syntax.md b/docs/framework/data/adonet/connection-string-syntax.md index ec19568add2f8..9e2d0be5d9660 100644 --- a/docs/framework/data/adonet/connection-string-syntax.md +++ b/docs/framework/data/adonet/connection-string-syntax.md @@ -113,7 +113,7 @@ You can also set the property of a allows you to get or set a connection string for an OLE DB data source, such as Microsoft Access. You can also create an `OleDb` connection string at run time by using the class. diff --git a/docs/framework/data/adonet/local-transactions.md b/docs/framework/data/adonet/local-transactions.md index 6e95f7b689bfe..11771c92f6962 100644 --- a/docs/framework/data/adonet/local-transactions.md +++ b/docs/framework/data/adonet/local-transactions.md @@ -15,7 +15,7 @@ Transactions in [!INCLUDE[vstecado](../../../../includes/vstecado-md.md)] are us Each of the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] data providers has its own `Transaction` object for performing local transactions. If you require a transaction to be performed in a SQL Server database, select a transaction. For an Oracle transaction, use the provider. In addition, there is a class that is available for writing provider-independent code that requires transactions. > [!NOTE] -> Transactions are most efficient when it is performed on the server. If you are working with a SQL Server database that makes extensive use of explicit transactions, consider writing them as stored procedures using the Transact-SQL BEGIN TRANSACTION statement. For more information about performing server-side transactions, see SQL Server Books Online. +> Transactions are most efficient when it is performed on the server. If you are working with a SQL Server database that makes extensive use of explicit transactions, consider writing them as stored procedures using the Transact-SQL BEGIN TRANSACTION statement. ## Performing a Transaction Using a Single Connection In [!INCLUDE[vstecado](../../../../includes/vstecado-md.md)], you control transactions with the `Connection` object. You can initiate a local transaction with the `BeginTransaction` method. Once you have begun a transaction, you can enlist a command in that transaction with the `Transaction` property of a `Command` object. You can then commit or roll back modifications made at the data source based on the success or failure of the components of the transaction. diff --git a/docs/framework/data/adonet/sql-server-data-type-mappings.md b/docs/framework/data/adonet/sql-server-data-type-mappings.md index bef9f5f6bc3b5..ca93b9b239717 100644 --- a/docs/framework/data/adonet/sql-server-data-type-mappings.md +++ b/docs/framework/data/adonet/sql-server-data-type-mappings.md @@ -46,8 +46,9 @@ SQL Server and the .NET Framework are based on different type systems. For examp 1 You cannot set the `DbType` property of a `SqlParameter` to `SqlDbType.Date`. 2 Use a specific typed accessor if you know the underlying type of the `sql_variant`. -## SQL Server Books Online Reference - For more information about SQL Server data types, see [Data Types (Database Engine)](http://go.microsoft.com/fwlink/?LinkID=107468). +## SQL Server documentation + +For more information about SQL Server data types, see [Data types (Transact-SQL)](/sql/t-sql/data-types/data-types-transact-sql). ## See Also [SQL Server Data Types and ADO.NET](../../../../docs/framework/data/adonet/sql/sql-server-data-types.md) diff --git a/docs/framework/data/adonet/sql/authentication-in-sql-server.md b/docs/framework/data/adonet/sql/authentication-in-sql-server.md index 59c64ef1dbdbb..7677de162e2eb 100644 --- a/docs/framework/data/adonet/sql/authentication-in-sql-server.md +++ b/docs/framework/data/adonet/sql/authentication-in-sql-server.md @@ -70,7 +70,7 @@ SQL Server supports two authentication modes, Windows authentication mode and mi |Resource|Description| |--------------|-----------------| -|[Principals](http://msdn.microsoft.com/library/bb543165.aspx) in SQL Server Books Online|Describes logins and other security principals in SQL Server.| +|[Principals](/sql/relational-databases/security/authentication-access/principals-database-engine)|Describes logins and other security principals in SQL Server.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/authorization-and-permissions-in-sql-server.md b/docs/framework/data/adonet/sql/authorization-and-permissions-in-sql-server.md index df62520139aa0..c1ff48662366a 100644 --- a/docs/framework/data/adonet/sql/authorization-and-permissions-in-sql-server.md +++ b/docs/framework/data/adonet/sql/authorization-and-permissions-in-sql-server.md @@ -50,7 +50,7 @@ When you create database objects, you must explicitly grant permissions to make |Resource|Description| |--------------|-----------------| -|[Permissions](http://msdn.microsoft.com/library/ms191291.aspx) in SQL Server Books Online|Contains topics describing permissions hierarchy, catalog views, and permissions of fixed server and database roles.| +|[Permissions](/sql/relational-databases/security/permissions-database-engine)|Contains topics describing permissions hierarchy, catalog views, and permissions of fixed server and database roles.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/clr-stored-procedures.md b/docs/framework/data/adonet/sql/clr-stored-procedures.md index 0f2e276ae0a80..4ebcb10cfb69d 100644 --- a/docs/framework/data/adonet/sql/clr-stored-procedures.md +++ b/docs/framework/data/adonet/sql/clr-stored-procedures.md @@ -9,15 +9,15 @@ Stored procedures are routines that cannot be used in scalar expressions. They c > [!NOTE] > Microsoft Visual Basic does not support output parameters in the same way that Microsoft Visual C# does. You must specify to pass the parameter by reference and apply the \ attribute to represent an output parameter, as in the following: -``` +```vb Public Shared Sub ExecuteToClient( ByRef number As Integer) -``` +``` - For more detailed information, see the version of SQL Server Books Online for the version of SQL Server you are using. +For more detailed information, see the version of [SQL Server documentation](/sql) for the version of SQL Server you're using. - **SQL Server Books Online** - -1. [CLR Stored Procedures](http://go.microsoft.com/fwlink/?LinkId=115400) + **SQL Server documentation** + +1. [CLR Stored Procedures](http://go.microsoft.com/fwlink/?LinkId=115400) ## See Also [Creating SQL Server 2005 Objects In Managed Code](http://msdn.microsoft.com/library/5358a825-e19b-49aa-8214-674ce5fed1da) diff --git a/docs/framework/data/adonet/sql/clr-triggers.md b/docs/framework/data/adonet/sql/clr-triggers.md index 11b2dc5f815fe..369ec0c72b548 100644 --- a/docs/framework/data/adonet/sql/clr-triggers.md +++ b/docs/framework/data/adonet/sql/clr-triggers.md @@ -6,11 +6,11 @@ ms.assetid: defe379c-30c7-487f-9abd-9c5e12ff49be # CLR Triggers A trigger is a special type of stored procedure that automatically runs when a language event executes. Because of the Microsoft SQL Server integration with the .NET Framework common language runtime (CLR), you can use any .NET Framework language to create CLR triggers. - For more detailed information, see the version of SQL Server Books Online for the version of SQL Server you are using. + For more detailed information, see the [SQL Server documentation](/sql) for the version of SQL Server you're using. - **SQL Server Books Online** + **SQL Server documentation** -1. [CLR Triggers](http://go.microsoft.com/fwlink/?LinkId=115397) +1. [CLR Triggers](/sql/database-engine/dev-guide/clr-triggers) ## See Also [Creating SQL Server 2005 Objects In Managed Code](http://msdn.microsoft.com/library/5358a825-e19b-49aa-8214-674ce5fed1da) diff --git a/docs/framework/data/adonet/sql/clr-user-defined-types.md b/docs/framework/data/adonet/sql/clr-user-defined-types.md index 7da4c4ff0bc2a..5642a9a730395 100644 --- a/docs/framework/data/adonet/sql/clr-user-defined-types.md +++ b/docs/framework/data/adonet/sql/clr-user-defined-types.md @@ -12,12 +12,12 @@ Microsoft SQL Server provides support for user-defined types (UDTs) implemented - Deep integration with other related server features. Once you define your own UDT, you can use it in all contexts where you can use a system type in SQL Server, including column definitions, and as variables, parameters, function results, cursors, triggers, and replication. - For more detailed information, see the version of SQL Server Books Online for the version of SQL Server you are using. + For more detailed information, see the [SQL Server documentation](/sql) for the version of SQL Server you're using. - **SQL Server Books Online** + **SQL Server documentation** -1. [CLR User-Defined Types](http://go.microsoft.com/fwlink/?LinkId=98366) +1. [CLR User-Defined Types](/sql/relational-databases/clr-integration-database-objects-user-defined-types/clr-user-defined-types) -## See Also - [Creating SQL Server 2005 Objects In Managed Code](http://msdn.microsoft.com/library/5358a825-e19b-49aa-8214-674ce5fed1da) - [ADO.NET Managed Providers and DataSet Developer Center](http://go.microsoft.com/fwlink/?LinkId=217917) +## See also + +[ADO.NET Overview](../ado-net-overview.md) \ No newline at end of file diff --git a/docs/framework/data/adonet/sql/comparing-guid-and-uniqueidentifier-values.md b/docs/framework/data/adonet/sql/comparing-guid-and-uniqueidentifier-values.md index b459ca7a6ed75..ffbdd897321d4 100644 --- a/docs/framework/data/adonet/sql/comparing-guid-and-uniqueidentifier-values.md +++ b/docs/framework/data/adonet/sql/comparing-guid-and-uniqueidentifier-values.md @@ -7,7 +7,7 @@ dev_langs: ms.assetid: aababd75-2335-43e3-ace8-4b7ae84191a8 --- # Comparing GUID and uniqueidentifier Values -The globally unique identifier (GUID) data type in SQL Server is represented by the `uniqueidentifier` data type, which stores a 16-byte binary value. A GUID is a binary number, and its main use is as an identifier that must be unique in a network that has many computers at many sites. GUIDs can be generated by calling the Transact-SQL NEWID function, and is guaranteed to be unique throughout the world. For more information, see "Using uniqueidentifier Data" in SQL Server Books Online. +The globally unique identifier (GUID) data type in SQL Server is represented by the `uniqueidentifier` data type, which stores a 16-byte binary value. A GUID is a binary number, and its main use is as an identifier that must be unique in a network that has many computers at many sites. GUIDs can be generated by calling the Transact-SQL NEWID function, and is guaranteed to be unique throughout the world. For more information, see [uniqueidentifier (Transact-SQL)](/sql/t-sql/data-types/uniqueidentifier-transact-sql). ## Working with SqlGuid Values Because GUIDs values are long and obscure, they are not meaningful for users. If randomly generated GUIDs are used for key values and you insert a lot of rows, you get random I/O into your indexes, which can negatively impact performance. GUIDs are also relatively large when compared to other data types. In general we recommend using GUIDs only for very narrow scenarios for which no other data type is suitable. @@ -40,5 +40,6 @@ Sorted SqlGuids: ``` ## See Also - [SQL Server Data Types and ADO.NET](../../../../../docs/framework/data/adonet/sql/sql-server-data-types.md) - [ADO.NET Managed Providers and DataSet Developer Center](http://go.microsoft.com/fwlink/?LinkId=217917) + +[SQL Server Data Types and ADO.NET](sql-server-data-types.md) +[ADO.NET Overview](../ado-net-overview.md) diff --git a/docs/framework/data/adonet/sql/creating-application-roles-in-sql-server.md b/docs/framework/data/adonet/sql/creating-application-roles-in-sql-server.md index d2f8cc5fe9610..81e0566af4332 100644 --- a/docs/framework/data/adonet/sql/creating-application-roles-in-sql-server.md +++ b/docs/framework/data/adonet/sql/creating-application-roles-in-sql-server.md @@ -50,7 +50,7 @@ Application roles provide a way to assign permissions to an application instead |Resource|Description| |--------------|-----------------| -|[Application Roles](http://msdn.microsoft.com/library/ms190998.aspx) in SQL Server Books Online|Describes how to create and use application roles in SQL Server 2008.| +|[Application Roles](/sql/relational-databases/security/authentication-access/application-roles)|Describes how to create and use application roles in SQL Server 2008.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/customizing-permissions-with-impersonation-in-sql-server.md b/docs/framework/data/adonet/sql/customizing-permissions-with-impersonation-in-sql-server.md index e54e536279feb..e17161d976f5f 100644 --- a/docs/framework/data/adonet/sql/customizing-permissions-with-impersonation-in-sql-server.md +++ b/docs/framework/data/adonet/sql/customizing-permissions-with-impersonation-in-sql-server.md @@ -59,14 +59,6 @@ CREATE PROCEDURE [procName] WITH EXECUTE AS 'proxyUser' AS ... - SELF. Executing as SELF executes in the security context of the creator of the stored procedure. This is equivalent to executing as a specified user, where the specified user is the person creating or altering the procedure. -## External Resources - For more information, see the following resources. - -|Resource|Description| -|--------------|-----------------| -|[Context Switching](http://msdn.microsoft.com/library/ms188268.aspx) in SQL Server Books Online|Contains links to topics describing how to use the EXECUTE AS clause.| -|[Using EXECUTE AS to Create Custom Permission Sets](http://msdn.microsoft.com/library/ms190384.aspx) and [Using EXECUTE AS in Modules](http://msdn.microsoft.com/library/ms178106.aspx) in SQL Server Books Online|Topics describe how to use the EXECUTE AS clause.| - ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) [Overview of SQL Server Security](../../../../../docs/framework/data/adonet/sql/overview-of-sql-server-security.md) diff --git a/docs/framework/data/adonet/sql/data-encryption-in-sql-server.md b/docs/framework/data/adonet/sql/data-encryption-in-sql-server.md index e2d8a2f07a18b..3df5dff9c62eb 100644 --- a/docs/framework/data/adonet/sql/data-encryption-in-sql-server.md +++ b/docs/framework/data/adonet/sql/data-encryption-in-sql-server.md @@ -13,15 +13,15 @@ SQL Server provides functions to encrypt and decrypt data using a certificate, a Within the scope of a database connection, SQL Server can maintain multiple open symmetric keys. An open key is retrieved from the store and is available for decrypting data. When a piece of data is decrypted, there is no need to specify the symmetric key to use. Each encrypted value contains the key identifier (key GUID) of the key used to encrypt it. The engine matches the encrypted byte stream to an open symmetric key, if the correct key has been decrypted and is open. This key is then used to perform decryption and return the data. If the correct key is not open, NULL is returned. - For an example that shows how to work with encrypted data in a database, see [How to: Encrypt a Column of Data](http://go.microsoft.com/fwlink/?LinkID=128559) in SQL Server Books Online. + For an example that shows how to work with encrypted data in a database, see [Encrypt a Column of Data](/sql/relational-databases/security/encryption/encrypt-a-column-of-data). ## External Resources For more information on data encryption, see the following resources. -||| +|Resource|Description| |-|-| -|[SQL Server Encryption](http://msdn.microsoft.com/library/bb510663.aspx) in SQL Server Books Online|Provides an overview of encryption in SQL Serve. This topic includes links to additional topics and how-to's.| -|[Encryption Hierarchy](http://msdn.microsoft.com/library/ms189586.aspx) and [Encryption How-to Topics](http://msdn.microsoft.com/library/aa337557.aspx) in SQL Server Books Online|Provides an overview of encryption in SQL Server. This topic provides links to additional topics and how-to's.| +|[SQL Server Encryption](/sql/relational-databases/security/encryption/sql-server-encryption)|Provides an overview of encryption in SQL Server. This topic includes links to additional articles.| +|[Encryption Hierarchy](/sql/relational-databases/security/encryption/encryption-hierarchy)|Provides an overview of encryption in SQL Server. This topic provides links to additional articles.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/database-mirroring-in-sql-server.md b/docs/framework/data/adonet/sql/database-mirroring-in-sql-server.md index 5f60c9a29b517..ec88ee24f62e4 100644 --- a/docs/framework/data/adonet/sql/database-mirroring-in-sql-server.md +++ b/docs/framework/data/adonet/sql/database-mirroring-in-sql-server.md @@ -51,11 +51,11 @@ string activeServer = connection.DataSource; > Mirroring support on the server is configured on a per-database basis. If data manipulation operations are executed against other databases not included in the principal/mirror set, either by using multipart names or by changing the current database, the changes to these other databases do not propagate in the event of failure. No error is generated when data is modified in a database that is not mirrored. The developer must evaluate the possible impact of such operations. ## Database Mirroring Resources - For conceptual documentation and information on configuring, deploying and administering mirroring, see the following resources in SQL Server Books Online. + For conceptual documentation and information on configuring, deploying and administering mirroring, see the following resources in SQL Server documentation. |Resource|Description| |--------------|-----------------| -|[Database Mirroring](http://msdn.microsoft.com/library/bb934127.aspx) in SQL Server Books Online|Describes how to set up and configure mirroring in SQL Server.| +|[Database Mirroring](/sql/database-engine/database-mirroring/database-mirroring-sql-server)|Describes how to set up and configure mirroring in SQL Server.| ## See Also [ADO.NET Managed Providers and DataSet Developer Center](http://go.microsoft.com/fwlink/?LinkId=217917) From 076a6a5ffcdd35b26b6bb98219b4c1ce97dc06df Mon Sep 17 00:00:00 2001 From: John Reese Date: Thu, 9 Aug 2018 19:27:57 -0400 Subject: [PATCH 02/13] Add bullets to see also section (#6876) --- docs/core/testing/unit-testing-published-output.md | 6 +++--- docs/core/testing/unit-testing-with-dotnet-test.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/testing/unit-testing-published-output.md b/docs/core/testing/unit-testing-published-output.md index 2407954b56d61..69c2cfadba0bd 100644 --- a/docs/core/testing/unit-testing-published-output.md +++ b/docs/core/testing/unit-testing-published-output.md @@ -28,6 +28,6 @@ dotnet vstest out/MyProject.Tests.dll > Note: If your app is targeting a framework other than `netcoreapp` you can still run the `dotnet vstest` command by passing in the targeted framework with a framework flag. For example, `dotnet vstest .dll --Framework:".NETFramework,Version=v4.6"`. In Visual Studio 2017 Update 5 the desired framework is automatically detected. ## See also -[Unit Testing with dotnet test and xUnit](unit-testing-with-dotnet-test.md) -[Unit Testing with dotnet test and NUnit](unit-testing-with-nunit.md) -[Unit Testing with dotnet test and MSTest](unit-testing-with-mstest.md) +- [Unit Testing with dotnet test and xUnit](unit-testing-with-dotnet-test.md) +- [Unit Testing with dotnet test and NUnit](unit-testing-with-nunit.md) +- [Unit Testing with dotnet test and MSTest](unit-testing-with-mstest.md) diff --git a/docs/core/testing/unit-testing-with-dotnet-test.md b/docs/core/testing/unit-testing-with-dotnet-test.md index 08340c761bfe7..804b4cfacd03a 100644 --- a/docs/core/testing/unit-testing-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-with-dotnet-test.md @@ -166,4 +166,4 @@ Continue to iterate by adding more tests, more theories, and more code in the ma ### Additional resources -[Testing controller logic in ASP.NET Core](/aspnet/core/mvc/controllers/testing) +- [Testing controller logic in ASP.NET Core](/aspnet/core/mvc/controllers/testing) From 7d3b4016bc9541bd2b60a883faa80b5907603edf Mon Sep 17 00:00:00 2001 From: Petr Kulikov <15279990+pkulikov@users.noreply.github.com> Date: Fri, 10 Aug 2018 16:51:10 +0200 Subject: [PATCH 03/13] Typo fix (#6928) --- docs/standard/threading/using-threads-and-threading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/threading/using-threads-and-threading.md b/docs/standard/threading/using-threads-and-threading.md index fa0865d422d54..bfeb187d99391 100644 --- a/docs/standard/threading/using-threads-and-threading.md +++ b/docs/standard/threading/using-threads-and-threading.md @@ -24,7 +24,7 @@ You create a new thread by creating a new instance of the method. That method raises a on the thread on which it's invoked. For more information, see [Destroying tThreads](destroying-threads.md). +To terminate the execution of a thread, use the method. That method raises a on the thread on which it's invoked. For more information, see [Destroying threads](destroying-threads.md). Beginning with the .NET Framework 4, you can use the to cancel a thread cooperatively. For more information, see [Canceling threads cooperatively](canceling-threads-cooperatively.md). From 0cecd7c65ad591c89f978b4fce37966f97873c97 Mon Sep 17 00:00:00 2001 From: Petr Kulikov <15279990+pkulikov@users.noreply.github.com> Date: Fri, 10 Aug 2018 17:19:43 +0200 Subject: [PATCH 04/13] ref keyword: removed empty section (#6854) --- docs/csharp/language-reference/keywords/ref.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/csharp/language-reference/keywords/ref.md b/docs/csharp/language-reference/keywords/ref.md index 475feec3ee8d0..1f92d48d89b00 100644 --- a/docs/csharp/language-reference/keywords/ref.md +++ b/docs/csharp/language-reference/keywords/ref.md @@ -15,7 +15,7 @@ The `ref` keyword indicates a value that is passed by reference. It is used in f - In a method signature and in a method call, to pass an argument to a method by reference. See [Passing an argument by reference](#passing-an-argument-by-reference) for more information. - In a method signature, to return a value to the caller by reference. See [Reference return values](#reference-return-values) for more information. - In a member body, to indicate that a reference return value is stored locally as a reference that the caller intends to modify or, in general, a local variable accesses another value by reference. See [Ref locals](#ref-locals) for more information. -- In a `struct` declaration to declare a `ref struct` or a `ref readonly struct`. See [ref struct declarations](#ref-struct-declarations) for more information. +- In a `struct` declaration to declare a `ref struct` or a `ref readonly struct`. For more information, see [Reference semantics with value types](../../reference-semantics-with-value-types.md). ## Passing an argument by reference @@ -117,8 +117,6 @@ When the caller stores the value returned by the `GetBookByTitle` method as a re [!code-csharp[csrefKeywordsMethodParams#6](../../../../samples/snippets/csharp/language-reference/keywords/in-ref-out-modifier/RefParameterModifier.cs#5)] -## Ref struct declarations - ## C# Language Specification [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] From e44540a85d675dcd8a5a6ce4949adc47e34f51a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johnny=20G=C3=A9rard?= <36079566+johnnyagerard@users.noreply.github.com> Date: Fri, 10 Aug 2018 17:24:07 +0200 Subject: [PATCH 05/13] Update namespace_1.cs (#6932) --- .../keywords/codesnippet/CSharp/namespace_1.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/csharp/language-reference/keywords/codesnippet/CSharp/namespace_1.cs b/docs/csharp/language-reference/keywords/codesnippet/CSharp/namespace_1.cs index 69d3e9380356b..ed68a8a1afcaa 100644 --- a/docs/csharp/language-reference/keywords/codesnippet/CSharp/namespace_1.cs +++ b/docs/csharp/language-reference/keywords/codesnippet/CSharp/namespace_1.cs @@ -3,7 +3,7 @@ namespace SampleNamespace { class SampleClass { } - interface SampleInterface { } + interface ISampleInterface { } struct SampleStruct { } @@ -15,4 +15,4 @@ namespace SampleNamespace.Nested { class SampleClass2 { } } -} \ No newline at end of file +} From cb5bedb7e921c060ac65e874c1dd0f50ce64070b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johnny=20G=C3=A9rard?= <36079566+johnnyagerard@users.noreply.github.com> Date: Fri, 10 Aug 2018 17:26:35 +0200 Subject: [PATCH 06/13] Update namespace.md (#6934) --- docs/csharp/language-reference/keywords/namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/language-reference/keywords/namespace.md b/docs/csharp/language-reference/keywords/namespace.md index 5a04b360354d8..e44a7a00f8d55 100644 --- a/docs/csharp/language-reference/keywords/namespace.md +++ b/docs/csharp/language-reference/keywords/namespace.md @@ -15,7 +15,7 @@ The `namespace` keyword is used to declare a scope that contains a set of relate [!code-csharp[csrefKeywordsNamespace#1](../../../csharp/language-reference/keywords/codesnippet/CSharp/namespace_1.cs)] ## Remarks - Within a namespace, you can declare one or more of the following types: + Within a namespace, you can declare zero or more of the following types: - another namespace From bbf956a61256b2dab225647544f05d09ccb4f3dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=B0=AD=E4=B9=9D=E9=BC=8E?= <109224573@qq.com> Date: Sat, 11 Aug 2018 00:48:49 +0800 Subject: [PATCH 07/13] Update docs about formatting-types (#6885) * Fix: Change from fr_FR to fr-FR * Fix code snippets * Fix blank space * Fix code snippets again * Update custom-numeric-format-strings.md * Update custom-numeric-format-strings.md --- docs/standard/base-types/custom-numeric-format-strings.md | 6 +++--- docs/standard/base-types/standard-numeric-format-strings.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/standard/base-types/custom-numeric-format-strings.md b/docs/standard/base-types/custom-numeric-format-strings.md index 982b03471a3fa..5d3e2e20205dc 100644 --- a/docs/standard/base-types/custom-numeric-format-strings.md +++ b/docs/standard/base-types/custom-numeric-format-strings.md @@ -41,7 +41,7 @@ You can create a custom numeric format string, which consists of one or more cus |"‰"|Per mille placeholder|Multiplies a number by 1000 and inserts a localized per mille symbol in the result string.

More information: [The "‰" Custom Specifier](#SpecifierPerMille).|0.03697 ("#0.00‰", en-US) -> 36.97‰

0.03697 ("#0.00‰", ru-RU) -> 36,97‰| |"E0"

"E+0"

"E-0"

"e0"

"e+0"

"e-0"|Exponential notation|If followed by at least one 0 (zero), formats the result using exponential notation. The case of "E" or "e" indicates the case of the exponent symbol in the result string. The number of zeros following the "E" or "e" character determines the minimum number of digits in the exponent. A plus sign (+) indicates that a sign character always precedes the exponent. A minus sign (-) indicates that a sign character precedes only negative exponents.

More information: [The "E" and "e" Custom Specifiers](#SpecifierExponent).|987654 ("#0.0e0") -> 98.8e4

1503.92311 ("0.0##e+00") -> 1.504e+03

1.8901385E-16 ("0.0e+00") -> 1.9e-16| |"\\"|Escape character|Causes the next character to be interpreted as a literal rather than as a custom format specifier.

More information: [The "\\" Escape Character](#SpecifierEscape).|987654 ("\\###00\\#") -> #987654#| -|'*string*'

"*string*"|Literal string delimiter|Indicates that the enclosed characters should be copied to the result string unchanged.

More information: [Character literals](#character-literals).|68 ("# ' degrees'") -> 68 degrees

68 ("#' degrees'") -> 68 degrees| +|'*string*'

"*string*"|Literal string delimiter|Indicates that the enclosed characters should be copied to the result string unchanged.

More information: [Character literals](#character-literals).|68 ("# 'degrees'") -> 68 degrees

68 ("#' degrees'") -> 68 degrees| |;|Section separator|Defines sections with separate format strings for positive, negative, and zero numbers.

More information: [The ";" Section Separator](#SectionSeparator).|12.345 ("#0.0#;(#0.0#);-\0-") -> 12.35

0 ("#0.0#;(#0.0#);-\0-") -> -0-

-12.345 ("#0.0#;(#0.0#);-\0-") -> (12.35)

12.345 ("#0.0#;(#0.0#)") -> 12.35

0 ("#0.0#;(#0.0#)") -> 0.0

-12.345 ("#0.0#;(#0.0#)") -> (12.35)| |Other|All other characters|The character is copied to the result string unchanged.

More information: [Character literals](#character-literals).|68 ("# °") -> 68 °| @@ -229,8 +229,8 @@ The following example illustrates one common use of literal character units (in The following example uses both approaches to include reserved characters in a custom numeric format string. - [!code-csharp-interactive[including reserved characters](~/samples/snippets/csharp/VS_Snippets_CLR/formatting.numeric.custom/cs/literal1.cs#1)] - [!code-vb[including reserved characters](~/samples/snippets/visualbasic/VS_Snippets_CLR/formatting.numeric.custom/vb/literal1.vb#1)] + [!code-csharp-interactive[including reserved characters](~/samples/snippets/csharp/VS_Snippets_CLR/formatting.numeric.custom/literal1.cs#1)] + [!code-vb[including reserved characters](~/samples/snippets/visualbasic/VS_Snippets_CLR/formatting.numeric.custom/literal1.vb#1)] ## Notes diff --git a/docs/standard/base-types/standard-numeric-format-strings.md b/docs/standard/base-types/standard-numeric-format-strings.md index 9675a6e61402c..2dcfa6e72e3a0 100644 --- a/docs/standard/base-types/standard-numeric-format-strings.md +++ b/docs/standard/base-types/standard-numeric-format-strings.md @@ -49,7 +49,7 @@ Standard numeric format strings are supported by: |----------------------|----------|-----------------|--------------| |"C" or "c"|Currency|Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString).|123.456 ("C", en-US) -> $123.46

123.456 ("C", fr-FR) -> 123,46 €

123.456 ("C", ja-JP) -> ¥123

-123.456 ("C3", en-US) -> ($123.456)

-123.456 ("C3", fr-FR) -> -123,456 €

-123.456 ("C3", ja-JP) -> -¥123.456| |"D" or "d"|Decimal|Result: Integer digits with optional negative sign.

Supported by: Integral types only.

Precision specifier: Minimum number of digits.

Default precision specifier: Minimum number of digits required.

More information: [The Decimal("D") Format Specifier](#DFormatString).|1234 ("D") -> 1234

-1234 ("D6") -> -001234| -|"E" or "e"|Exponential (scientific)|Result: Exponential notation.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: 6.

More information: [The Exponential ("E") Format Specifier](#EFormatString).|1052.0329112756 ("E", en-US) -> 1.052033E+003

1052.0329112756 ("e", fr-FR) -> 1,052033e+003

-1052.0329112756 ("e2", en-US) -> -1.05e+003

-1052.0329112756 ("E2", fr_FR) -> -1,05E+003| +|"E" or "e"|Exponential (scientific)|Result: Exponential notation.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: 6.

More information: [The Exponential ("E") Format Specifier](#EFormatString).|1052.0329112756 ("E", en-US) -> 1.052033E+003

1052.0329112756 ("e", fr-FR) -> 1,052033e+003

-1052.0329112756 ("e2", en-US) -> -1.05e+003

-1052.0329112756 ("E2", fr-FR) -> -1,05E+003| |"F" or "f"|Fixed-point|Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Fixed-Point ("F") Format Specifier](#FFormatString).|1234.567 ("F", en-US) -> 1234.57

1234.567 ("F", de-DE) -> 1234,57

1234 ("F1", en-US) -> 1234.0

1234 ("F1", de-DE) -> 1234,0

-1234.56 ("F4", en-US) -> -1234.5600

-1234.56 ("F4", de-DE) -> -1234,5600| |"G" or "g"|General|Result: The more compact of either fixed-point or scientific notation.

Supported by: All numeric types.

Precision specifier: Number of significant digits.

Default precision specifier: Depends on numeric type.

More information: [The General ("G") Format Specifier](#GFormatString).|-123.456 ("G", en-US) -> -123.456

-123.456 ("G", sv-SE) -> -123,456

123.4546 ("G4", en-US) -> 123.5

123.4546 ("G4", sv-SE) -> 123,5

-1.234567890e-25 ("G", en-US) -> -1.23456789E-25

-1.234567890e-25 ("G", sv-SE) -> -1,23456789E-25| |"N" or "n"|Number|Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Numeric ("N") Format Specifier](#NFormatString).|1234.567 ("N", en-US) -> 1,234.57

1234.567 ("N", ru-RU) -> 1 234,57

1234 ("N1", en-US) -> 1,234.0

1234 ("N1", ru-RU) -> 1 234,0

-1234.56 ("N3", en-US) -> -1,234.560

-1234.56 ("N3", ru-RU) -> -1 234,560| From 272a6c96c53d8cda2e18a1b7c7a9dda0d093b6ee Mon Sep 17 00:00:00 2001 From: John Alexander Date: Fri, 10 Aug 2018 13:20:09 -0500 Subject: [PATCH 08/13] Fixed URL (#6944) --- docs/framework/wcf/how-to-create-a-wcf-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework/wcf/how-to-create-a-wcf-client.md b/docs/framework/wcf/how-to-create-a-wcf-client.md index e3d35e9b82040..ecd1eeb2f7623 100644 --- a/docs/framework/wcf/how-to-create-a-wcf-client.md +++ b/docs/framework/wcf/how-to-create-a-wcf-client.md @@ -29,7 +29,7 @@ This is the fourth of six tasks required to create a Windows Communication Found 3. Add a reference to System.ServiceModel to the GettingStartedClient project by right-clicking the **Reference** folder under the GettingStartedClient project in Solution Explorer and select **Add** Reference. In the **Add Reference** dialog select **Framework** on the left-hand side of the dialog. In the Search Assemblies textbox, type in `System.ServiceModel`. In the center section of the dialog select **System.ServiceModel**, click the **Add** button, and click the **Close** button. Save the solution by clicking the **Save All** button below the main menu. -4. Next you wlll add a service reference to the Calculator Service. Before you can do that, you must start up the GettingStartedHost console application. Once the host is running you can right click the References folder under the GettingStartedClient project in the Solution Explorer and select Add Service Reference and type in the following URL in the address box of the Add Service Reference dialog: HYPERLINK "http://localhost:8000/ServiceModelSamples/Service" http://localhost:8000/ServiceModelSamples/Service and click the **Go** button. The CalculatorService should then be displayed in the Services list box, Double click CalculatorService and it will expand and show the service contracts implemented by the service. Leave the default namespace as is and click the **OK** button. +4. Next you wlll add a service reference to the Calculator Service. Before you can do that, you must start up the GettingStartedHost console application. Once the host is running you can right click the References folder under the GettingStartedClient project in the Solution Explorer and select Add Service Reference and type in the following URL in the address box of the Add Service Reference dialog: [http://localhost:8000/ServiceModelSamples/Service](http://localhost:8000/ServiceModelSamples/Service) and click the **Go** button. The CalculatorService should then be displayed in the Services list box, Double click CalculatorService and it will expand and show the service contracts implemented by the service. Leave the default namespace as is and click the **OK** button. When you add a reference to a service using Visual Studio a new item will appear in the Solution Explorer under the Service References folder under the GettingStartedClient project. If you use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) tool a source code file and app.config file will be generated. From c4f62325eb6e3c2a4c318c10af3d66b0768d36bd Mon Sep 17 00:00:00 2001 From: John Alexander Date: Fri, 10 Aug 2018 14:01:30 -0500 Subject: [PATCH 09/13] Revising first paragraph for SEO. (#6948) --- docs/core/docker/docker-basics-dotnet-core.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/docker/docker-basics-dotnet-core.md b/docs/core/docker/docker-basics-dotnet-core.md index 5766366189afb..26db93a2ae448 100644 --- a/docs/core/docker/docker-basics-dotnet-core.md +++ b/docs/core/docker/docker-basics-dotnet-core.md @@ -10,15 +10,15 @@ ms.custom: mvc # Learn Docker Basics with .NET Core -This tutorial teaches the Docker container build and deploy tasks for a .NET Core application. During the course of this tutorial, you learn: +This tutorial teaches the Docker container build and deploy tasks for a .NET Core application. The [Docker platform](https://docs.docker.com/engine/docker-overview/#the-docker-platform) uses the [Docker Engine](https://docs.docker.com/engine/docker-overview/#docker-engine) to quickly build and package apps as [Docker images](https://docs.docker.com/glossary/?term=image). These images are written in the [Dockerfile](https://docs.docker.com/glossary/?term=Dockerfile) format to be deployed and run in a [layered container](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/#container-and-layers). + +During the course of this tutorial, you learn: > [!div class="checklist"] > * How to create a Dockerfile > * How to create a .NET Core app. > * How to deploy your app into a Docker container. -The [Docker platform](https://docs.docker.com/engine/docker-overview/#the-docker-platform) uses the [Docker Engine](https://docs.docker.com/engine/docker-overview/#docker-engine) to quickly build and package apps as [Docker images](https://docs.docker.com/glossary/?term=image). These images are written in the [Dockerfile](https://docs.docker.com/glossary/?term=Dockerfile) format to be deployed and run in a [layered container](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/#container-and-layers). - ## .NET Core: Easiest way to get started Before creating the Docker image, you need an application to containerize. You can create it on Linux, MacOS, or Windows. The quickest and easiest way to do that is to use .NET Core. @@ -284,4 +284,4 @@ The following Docker images are used in this sample * [ASP.NET Core on DockerHub](https://hub.docker.com/r/microsoft/aspnetcore/) * [Dockerize a .NET Core application - Docker Tutorial](https://docs.docker.com/engine/examples/dotnetcore/) * [Working with Visual Studio Docker Tools](https://docs.microsoft.com/aspnet/core/publishing/visual-studio-tools-for-docker) -* [Deploying Docker Images from the Azure Container Registry to Azure Container Instances](https://blogs.msdn.microsoft.com/stevelasker/2017/07/28/deploying-docker-images-from-the-azure-container-registry-to-azure-container-instances/) \ No newline at end of file +* [Deploying Docker Images from the Azure Container Registry to Azure Container Instances](https://blogs.msdn.microsoft.com/stevelasker/2017/07/28/deploying-docker-images-from-the-azure-container-registry-to-azure-container-instances/) From f9dfa5b0de2372551829600c9b21897ae27239e7 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 10 Aug 2018 12:52:43 -0700 Subject: [PATCH 10/13] Escaped asterisks (#6942) --- docs/framework/migration-guide/versions-and-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework/migration-guide/versions-and-dependencies.md b/docs/framework/migration-guide/versions-and-dependencies.md index 99ba0e6b3aa2a..8f7c66e3b44d4 100644 --- a/docs/framework/migration-guide/versions-and-dependencies.md +++ b/docs/framework/migration-guide/versions-and-dependencies.md @@ -34,7 +34,7 @@ Each version of the .NET Framework contains the common language runtime (CLR), t |4.5.1

[New features](../whats-new/index.md#whats-new-in-the-net-framework-451)|4|2013|✓ 8.1
+ 8
+ 7
+ Vista|✓ 2012 R2
+ 2012
+ 2008 R2 SP1
+ 2008 SP2|Use `Release` DWORD:

- 378675 (Windows 8.1)
- 378758 (all other)

(see [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md))| |4.5

[New features](../whats-new/index.md#whats-new-in-the-net-framework-45)|4|2012|✓ 8
+ 7
+ Vista|✓ 2012
+ 2008 R2 SP1
+ 2008 SP2|Use `Release` DWORD:

378389

(see [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md))| |4

[New features](http://msdn.microsoft.com/library/ms171868\(v=vs.100\).aspx)|4|2010|+ 7
+ Vista|+ 2008 R2 SP1
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| -|3.5

[New features](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2008/ms171868\(v=vs.90\))|2.0|2008|✓ 10*
✓ 8.1*
✓ 8\*
✓ 7
+ Vista|✓2008 R2 SP1*
+ 2012 R2*
+ 2012*
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| +|3.5

[New features](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2008/ms171868\(v=vs.90\))|2.0|2008|✓ 10\*
✓ 8.1\*
✓ 8\*
✓ 7
+ Vista|✓2008 R2 SP1\*
+ 2012 R2\*
+ 2012\*
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |3.0

New:
WPF, WCF, WF, CardSpace|2.0|-|✓ Vista|✓ 2008 R2 SP1*
✓ 2008 SP2\*
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |2.0

[New features](https://docs.microsoft.com/previous-versions/dotnet/netframework-2.0/ms229284\(v%3dvs.80\))|2.0|2005|-|✓ 2008 R2 SP1
✓ 2008 SP2
✓ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |1.1

[New features](https://docs.microsoft.com/previous-versions/dotnet/netframework-1.1/9wtde3k4\(v%3dvs.71\))|1.1|2003|-|✓ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| From 63f0f6ecebca6dfd96b3a1a73587d82b43c607bc Mon Sep 17 00:00:00 2001 From: Mike B Date: Fri, 10 Aug 2018 17:54:02 -0700 Subject: [PATCH 11/13] =?UTF-8?q?converted=20additonal=20msdn=20links=20to?= =?UTF-8?q?=20site-relative,=20mostly=20to=20windows=20co=E2=80=A6=20(#686?= =?UTF-8?q?5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * converted additonal msdn links to site-relative, mostly to windows content * fixed broken links * more broken links fixed * changed /previous-versions/ to http links * fixed links * fixed last link * actually fixed last link * fixed bad links due to en-us --- docs/core/additional-tools/index.md | 2 +- docs/csharp/expression-classes.md | 2 +- docs/csharp/expression-trees-interpreting.md | 2 +- .../compiler-options/codepage-compiler-option.md | 2 +- .../preferreduilang-compiler-option.md | 2 +- .../compiler-options/win32icon-compiler-option.md | 2 +- docs/csharp/language-reference/keywords/for.md | 2 +- .../csharp/language-reference/keywords/foreach-in.md | 2 +- .../csharp/programming-guide/concepts/async/index.md | 2 +- docs/csharp/programming-guide/concepts/index.md | 2 +- .../programming-guide/types/boxing-and-unboxing.md | 2 +- docs/csharp/tuples.md | 2 +- .../how-to-install-an-assembly-into-the-gac.md | 2 +- .../how-to-remove-an-assembly-from-the-gac.md | 2 +- .../manipulations-and-inertia-overview.md | 2 +- .../data/adonet/sql/clr-user-defined-functions.md | 2 +- .../enabling-cross-database-access-in-sql-server.md | 2 +- docs/framework/data/adonet/sql/filestream-data.md | 2 +- docs/framework/data/adonet/sql/index.md | 2 +- ...rmissions-with-stored-procedures-in-sql-server.md | 2 +- .../sql/server-and-database-roles-in-sql-server.md | 6 +++--- .../sql/signing-stored-procedures-in-sql-server.md | 2 +- .../data/adonet/sql/table-valued-parameters.md | 2 +- .../deployment/deployment-guide-for-developers.md | 2 +- .../framework/deployment/guide-for-administrators.md | 2 +- docs/framework/develop-client-apps.md | 2 +- docs/framework/install/guide-for-developers.md | 2 +- ...ure-net-framework-based-com-components-for-reg.md | 4 ++-- .../interop/registration-free-com-interop.md | 4 ++-- .../migration-guide/mitigation-path-normalization.md | 2 +- .../net-framework-4-migration-issues.md | 6 +++--- .../migration-guide/versions-and-dependencies.md | 2 +- ...migrating-your-windows-store-app-to-net-native.md | 8 ++++---- .../network-programming-samples.md | 2 +- ...re-applications-and-services-using-wif-tracing.md | 4 ++-- docs/framework/tools/signtool-exe.md | 8 ++++---- .../axl-authenticode-signer-info-structure.md | 2 +- .../axl-authenticode-timestamper-info-structure.md | 2 +- .../axlgetissuerpublickeyhash-function.md | 2 +- .../axlrsakeyvaluetopublickeytoken-function.md | 4 ++-- .../certtimestampauthenticodelicense-function.md | 4 ++-- .../certverifyauthenticodelicense-function.md | 2 +- ...lrdatatarget3-getexceptioncontextrecord-method.md | 6 +++--- .../iclrdatatarget3-getexceptionrecord-method.md | 8 ++++---- ...debugmutabledatatarget-setthreadcontext-method.md | 2 +- .../ibindingdisplay-getcurrentdisplay-method.md | 2 +- ...ymunmanagedencupdate-updatesymbolstore2-method.md | 2 +- .../fusion/iassemblycacheitem-createstream-method.md | 2 +- .../hosting/corbindtoruntimeex-function.md | 2 +- .../hosting/corbindtoruntimehost-function.md | 2 +- .../hosting/startup-flags-enumeration.md | 2 +- .../metadata/coropenflags-enumeration.md | 2 +- ...etadatadispenserex-openscopeonitypeinfo-method.md | 2 +- .../clr-profilers-and-windows-store-apps.md | 12 ++++++------ .../unmanaged-api/profiling/profiling-overview.md | 2 +- .../unmanaged-api/tlbexp/gettypelibinfo-function.md | 6 +++--- .../tlbexp/itypelibresolver-interface.md | 2 +- .../tlbexp/loadtypelibwithresolver-function.md | 4 ++-- .../unmanaged-api/tlbexp/resolvetypelib-method.md | 10 +++++----- docs/framework/unmanaged-api/wmi/beginenumeration.md | 4 ++-- .../unmanaged-api/wmi/beginmethodenumeration.md | 6 +++--- .../unmanaged-api/wmi/blessiwbemservices.md | 4 ++-- .../unmanaged-api/wmi/blessiwbemservicesobject.md | 2 +- docs/framework/unmanaged-api/wmi/clone.md | 4 ++-- .../unmanaged-api/wmi/cloneenumwbemclassobject.md | 8 ++++---- docs/framework/unmanaged-api/wmi/compareto.md | 6 +++--- docs/framework/unmanaged-api/wmi/connectserverwmi.md | 4 ++-- .../unmanaged-api/wmi/createclassenumwmi.md | 6 +++--- .../unmanaged-api/wmi/createinstanceenumwmi.md | 6 +++--- docs/framework/unmanaged-api/wmi/delete.md | 4 ++-- docs/framework/unmanaged-api/wmi/deletemethod.md | 6 +++--- docs/framework/unmanaged-api/wmi/endenumeration.md | 4 ++-- .../unmanaged-api/wmi/endmethodenumeration.md | 4 ++-- .../unmanaged-api/wmi/execnotificationquerywmi.md | 6 +++--- docs/framework/unmanaged-api/wmi/execquerywmi.md | 8 ++++---- .../unmanaged-api/wmi/formatfromrawvalue.md | 2 +- docs/framework/unmanaged-api/wmi/get.md | 8 ++++---- .../unmanaged-api/wmi/getcurrentapartmenttype.md | 6 +++--- .../unmanaged-api/wmi/getdemultiplexedstub.md | 2 +- docs/framework/unmanaged-api/wmi/geterrorinfo.md | 4 ++-- docs/framework/unmanaged-api/wmi/getmethod.md | 12 ++++++------ docs/framework/unmanaged-api/wmi/getmethodorigin.md | 4 ++-- .../unmanaged-api/wmi/getmethodqualifierset.md | 8 ++++---- docs/framework/unmanaged-api/wmi/getnames.md | 4 ++-- docs/framework/unmanaged-api/wmi/getobjecttext.md | 4 ++-- .../framework/unmanaged-api/wmi/getpropertyhandle.md | 6 +++--- .../framework/unmanaged-api/wmi/getpropertyorigin.md | 4 ++-- .../unmanaged-api/wmi/getpropertyqualifierset.md | 10 +++++----- docs/framework/unmanaged-api/wmi/getqualifierset.md | 6 +++--- docs/framework/unmanaged-api/wmi/index.md | 2 +- docs/framework/unmanaged-api/wmi/inheritsfrom.md | 4 ++-- docs/framework/unmanaged-api/wmi/next.md | 4 ++-- docs/framework/unmanaged-api/wmi/nextmethod.md | 10 +++++----- docs/framework/unmanaged-api/wmi/put.md | 8 ++++---- docs/framework/unmanaged-api/wmi/putclasswmi.md | 6 +++--- docs/framework/unmanaged-api/wmi/putinstancewmi.md | 6 +++--- docs/framework/unmanaged-api/wmi/putmethod.md | 12 ++++++------ .../wmi/qualifierset-beginenumeration.md | 4 ++-- .../unmanaged-api/wmi/qualifierset-delete.md | 4 ++-- .../unmanaged-api/wmi/qualifierset-endenumeration.md | 4 ++-- docs/framework/unmanaged-api/wmi/qualifierset-get.md | 4 ++-- .../unmanaged-api/wmi/qualifierset-getnames.md | 4 ++-- .../framework/unmanaged-api/wmi/qualifierset-next.md | 4 ++-- docs/framework/unmanaged-api/wmi/qualifierset-put.md | 4 ++-- .../framework/unmanaged-api/wmi/spawnderivedclass.md | 4 ++-- docs/framework/unmanaged-api/wmi/spawninstance.md | 4 ++-- .../unmanaged-api/wmi/writepropertyvalue.md | 4 ++-- docs/framework/wcf/diagnostics/wmi/index.md | 2 +- docs/framework/wcf/feature-details/error-handling.md | 4 ++-- docs/framework/wcf/samples/wmi-provider.md | 2 +- docs/framework/whats-new/index.md | 6 +++--- .../how-to-debug-windows-service-applications.md | 4 ++-- ...-service-application-in-the-component-designer.md | 6 +++--- .../wpf/advanced/cleartype-registry-settings.md | 2 +- ...-object-model-windows-forms-and-com-versus-wpf.md | 10 +++++----- .../walkthrough-hosting-wpf-content-in-win32.md | 4 ++-- docs/framework/wpf/getting-started/index.md | 2 +- .../graphics-multimedia/bitmap-effects-overview.md | 4 ++-- .../extend-glass-frame-into-a-wpf-application.md | 10 +++++----- .../wpf/graphics-multimedia/imaging-overview.md | 2 +- .../wpf-graphics-rendering-overview.md | 2 +- ...rm-development-with-the-portable-class-library.md | 2 +- ...ort-for-windows-store-apps-and-windows-runtime.md | 6 +++--- docs/standard/events/index.md | 2 +- docs/standard/io/file-path-formats.md | 6 +++--- docs/standard/io/how-to-read-text-from-a-file.md | 2 +- docs/standard/io/index.md | 8 ++++---- docs/standard/io/isolated-storage.md | 2 +- docs/standard/io/types-of-isolation.md | 2 +- docs/standard/security/vulnerabilities-cbc-mode.md | 10 +++++----- .../managed-and-unmanaged-threading-in-windows.md | 4 ++-- .../threading/pausing-and-resuming-threads.md | 2 +- 132 files changed, 271 insertions(+), 271 deletions(-) diff --git a/docs/core/additional-tools/index.md b/docs/core/additional-tools/index.md index 6e71fc3a902f7..5052e0a6c6f01 100644 --- a/docs/core/additional-tools/index.md +++ b/docs/core/additional-tools/index.md @@ -17,7 +17,7 @@ The WCF (Windows Communication Foundation) Web Service Reference is a Visual Stu ## [WCF dotnet-svcutil tool](dotnet-svcutil-guide.md) The WCF (Windows Communication Foundation) dotnet-svcutil tool is a .NET Core CLI tool that retrieves metadata from a web service on a network location or from a WSDL file, and generates a source file compatible with .NET Core, defining a WCF proxy class with methods that you can use to access the web service operations. -The **dotnet-svcutil** tool is an alternative option to the [**WCF Web Service Reference**](/dotnet/core/additional-tools/wcf-web-service-reference-guide) Visual Studio connected service provider which first shipped with Visual Studio 2017 v15.5. The **dotnet-svcutil** tool as a .NET Core CLI tool, is available cross-platform on Linux, macOS, and Windows. +The **dotnet-svcutil** tool is an alternative option to the [**WCF Web Service Reference**](wcf-web-service-reference-guide.md) Visual Studio connected service provider which first shipped with Visual Studio 2017 v15.5. The **dotnet-svcutil** tool as a .NET Core CLI tool, is available cross-platform on Linux, macOS, and Windows. ## [XML Serializer Generator](xml-serializer-generator.md) diff --git a/docs/csharp/expression-classes.md b/docs/csharp/expression-classes.md index 9fff86b31119e..4d719761fec7d 100644 --- a/docs/csharp/expression-classes.md +++ b/docs/csharp/expression-classes.md @@ -11,7 +11,7 @@ ms.assetid: e9c85021-0d36-48af-91b7-aaaa66f22654 There is a large list of classes in the .NET Core framework that work with Expression Trees. You can see the full -list [here](/dotnet/core/api/System.Linq.Expressions). +list at . Rather than run through the full list, let's understand how the framework classes have been designed. In language design, an expression is a body of code that evaluates and returns a value. Expressions diff --git a/docs/csharp/expression-trees-interpreting.md b/docs/csharp/expression-trees-interpreting.md index 3ea56e03fe680..4e8655cdbe734 100644 --- a/docs/csharp/expression-trees-interpreting.md +++ b/docs/csharp/expression-trees-interpreting.md @@ -581,7 +581,7 @@ capabilities. Even the last example recognizes a subset of the possible node types. You can still feed it many expressions that will cause it to fail. A full implementation is included in the .NET Standard -under the name [ExpressionVisitor](/dotnet/core/api/System.Linq.Expressions.ExpressionVisitor) +under the name and can handle all the possible node types. Finally, the library I used in this article was built for demonstration diff --git a/docs/csharp/language-reference/compiler-options/codepage-compiler-option.md b/docs/csharp/language-reference/compiler-options/codepage-compiler-option.md index 0883f43e5da7c..5992134d8e788 100644 --- a/docs/csharp/language-reference/compiler-options/codepage-compiler-option.md +++ b/docs/csharp/language-reference/compiler-options/codepage-compiler-option.md @@ -27,7 +27,7 @@ This option specifies which codepage to use during compilation if the required p If the source code files were created with the same codepage that is in effect on your computer or if the source code files were created with UNICODE or UTF-8, you need not use **-codepage**. - See [GetCPInfo](https://msdn.microsoft.com/library/dd318078(VS.85).aspx) for information on how to find which code pages are supported on your system. + See [GetCPInfo](/windows/desktop/api/winnls/nf-winnls-getcpinfo) for information on how to find which code pages are supported on your system. This compiler option is unavailable in Visual Studio and cannot be changed programmatically. diff --git a/docs/csharp/language-reference/compiler-options/preferreduilang-compiler-option.md b/docs/csharp/language-reference/compiler-options/preferreduilang-compiler-option.md index 4356e1309308c..b384ce5c987a8 100644 --- a/docs/csharp/language-reference/compiler-options/preferreduilang-compiler-option.md +++ b/docs/csharp/language-reference/compiler-options/preferreduilang-compiler-option.md @@ -20,7 +20,7 @@ By using the `-preferreduilang` compiler option, you can specify the language in ## Arguments `language` - The [language name](https://msdn.microsoft.com/library/windows/desktop/dd318696(v=vs.85).aspx) of the language to use for compiler output. + The [language name](/windows/desktop/Intl/language-names) of the language to use for compiler output. ## Remarks You can use the `-preferreduilang` compiler option to specify the language that you want the C# compiler to use for error messages and other command-line output. If the language pack for the language is not installed, the language setting of the operating system is used instead, and no error is reported. diff --git a/docs/csharp/language-reference/compiler-options/win32icon-compiler-option.md b/docs/csharp/language-reference/compiler-options/win32icon-compiler-option.md index 1eb07ae04e29e..fb7dd382e8adb 100644 --- a/docs/csharp/language-reference/compiler-options/win32icon-compiler-option.md +++ b/docs/csharp/language-reference/compiler-options/win32icon-compiler-option.md @@ -23,7 +23,7 @@ The **-win32icon** option inserts an .ico file in the output file, which gives t The .ico file that you want to add to your output file. ## Remarks - An .ico file can be created with the [Resource Compiler](https://msdn.microsoft.com/library/aa381042.aspx). The Resource Compiler is invoked when you compile a Visual C++ program; an .ico file is created from the .rc file. + An .ico file can be created with the [Resource Compiler](/windows/desktop/menurc/resource-compiler). The Resource Compiler is invoked when you compile a Visual C++ program; an .ico file is created from the .rc file. See [-linkresource](../../../csharp/language-reference/compiler-options/linkresource-compiler-option.md) (to reference) or [-resource](../../../csharp/language-reference/compiler-options/resource-compiler-option.md) (to attach) a .NET Framework resource file. See [-win32res](../../../csharp/language-reference/compiler-options/win32res-compiler-option.md) to import a .res file. diff --git a/docs/csharp/language-reference/keywords/for.md b/docs/csharp/language-reference/keywords/for.md index 16e92de149abf..4d769bea8214f 100644 --- a/docs/csharp/language-reference/keywords/for.md +++ b/docs/csharp/language-reference/keywords/for.md @@ -103,7 +103,7 @@ The following example defines the infinite `for` loop: ## See also -[The for statement (C# language specification)](/dotnet/csharp/language-reference/language-specification/statements#the-for-statement) +[The for statement (C# language specification)](../language-specification/index.md) [C# Reference](../index.md) [C# Programming Guide](../../programming-guide/index.md) [C# Keywords](index.md) diff --git a/docs/csharp/language-reference/keywords/foreach-in.md b/docs/csharp/language-reference/keywords/foreach-in.md index 93064248ac698..3d6a301309c97 100644 --- a/docs/csharp/language-reference/keywords/foreach-in.md +++ b/docs/csharp/language-reference/keywords/foreach-in.md @@ -41,7 +41,7 @@ Beginning with C# 7.3, if the enumerator's `Current` property returns a [referen ## See also -[The foreach statement (C# language specification)](/dotnet/csharp/language-reference/language-specification/statements#the-foreach-statement) +[The foreach statement (C# language specification)](../language-specification/index.md) [Using foreach with Arrays](../../programming-guide/arrays/using-foreach-with-arrays.md) [for](for.md) [Iteration Statements](iteration-statements.md) diff --git a/docs/csharp/programming-guide/concepts/async/index.md b/docs/csharp/programming-guide/concepts/async/index.md index 61c6ea0c5bce3..22ba4d4312281 100644 --- a/docs/csharp/programming-guide/concepts/async/index.md +++ b/docs/csharp/programming-guide/concepts/async/index.md @@ -134,7 +134,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 . - 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)](/previous-versions/windows/apps/hh464924(v=win.10)) and [Quickstart: Calling asynchronous APIs in C# or Visual Basic](/previous-versions/windows/apps/hh452713(v=win.10)) if you use earlier versions of the Windows Runtime. + 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. ## Threads Async methods are intended to be non-blocking operations. An `await` expression in an async method doesn’t block the current thread while the awaited task is running. Instead, the expression signs up the rest of the method as a continuation and returns control to the caller of the async method. diff --git a/docs/csharp/programming-guide/concepts/index.md b/docs/csharp/programming-guide/concepts/index.md index c204457bab2a5..df0481cae9a0a 100644 --- a/docs/csharp/programming-guide/concepts/index.md +++ b/docs/csharp/programming-guide/concepts/index.md @@ -28,4 +28,4 @@ This section explains programming concepts in the C# language. ||| |---|---| -|[Performance Tips](https://msdn.microsoft.com/library/ms173196(VS.110).aspx) | Discusses several basic rules that may help you increase the performance of your application.| +|[Performance Tips](../../../../docs/framework/performance/performance-tips.md) | Discusses several basic rules that may help you increase the performance of your application.| diff --git a/docs/csharp/programming-guide/types/boxing-and-unboxing.md b/docs/csharp/programming-guide/types/boxing-and-unboxing.md index f27853f3ba73a..6e0354862a7ab 100644 --- a/docs/csharp/programming-guide/types/boxing-and-unboxing.md +++ b/docs/csharp/programming-guide/types/boxing-and-unboxing.md @@ -26,7 +26,7 @@ Boxing is the process of converting a [value type](../../../csharp/language-refe [!code-csharp[csProgGuideTypes#47](../../../csharp/programming-guide/nullable-types/codesnippet/CSharp/boxing-and-unboxing_3.cs)] ## Performance - In relation to simple assignments, boxing and unboxing are computationally expensive processes. When a value type is boxed, a new object must be allocated and constructed. To a lesser degree, the cast required for unboxing is also expensive computationally. For more information, see [Performance](https://msdn.microsoft.com/library/ms173196(VS.110).aspx). + In relation to simple assignments, boxing and unboxing are computationally expensive processes. When a value type is boxed, a new object must be allocated and constructed. To a lesser degree, the cast required for unboxing is also expensive computationally. For more information, see [Performance](../../../../docs/framework/performance/performance-tips.md). ## Boxing Boxing is used to store value types in the garbage-collected heap. Boxing is an implicit conversion of a [value type](../../../csharp/language-reference/keywords/value-types.md) to the type `object` or to any interface type implemented by this value type. Boxing a value type allocates an object instance on the heap and copies the value into the new object. diff --git a/docs/csharp/tuples.md b/docs/csharp/tuples.md index f9b7c18963835..05b173c4ff558 100644 --- a/docs/csharp/tuples.md +++ b/docs/csharp/tuples.md @@ -153,7 +153,7 @@ Beginning with C# 7.3, tuple types support the `==` and `!=` operators. These op [!code-csharp[TupleEquality](../../samples/snippets/csharp/tuples/tuples/program.cs#Equality "Testing tuples for equality")] -There are several rules that make tuple equality tests more convenient. Tuple equality performs [lifted conversions](/dotnet/csharp/language-reference/language-specification/conversions#lifted-conversion-operators) if one of the tuples is a nullable tuple, as shown in the following code: +There are several rules that make tuple equality tests more convenient. Tuple equality performs [lifted conversions](language-reference/language-specification/index.md) if one of the tuples is a nullable tuple, as shown in the following code: [!code-csharp[NullableTupleEquality](../../samples/snippets/csharp/tuples/tuples/program.cs#NullableEquality "Comparing Tuples and nullable tuples")] diff --git a/docs/framework/app-domains/how-to-install-an-assembly-into-the-gac.md b/docs/framework/app-domains/how-to-install-an-assembly-into-the-gac.md index 50ba529d66736..e1537b2fa961e 100644 --- a/docs/framework/app-domains/how-to-install-an-assembly-into-the-gac.md +++ b/docs/framework/app-domains/how-to-install-an-assembly-into-the-gac.md @@ -17,7 +17,7 @@ There are two ways to install a strong-named assembly into the global assembly c > [!IMPORTANT] > Only strong-named assemblies can be installed into the GAC. For information about how to create a strong-named assembly, see [How to: Sign an Assembly with a Strong Name](../../../docs/framework/app-domains/how-to-sign-an-assembly-with-a-strong-name.md). -- Using [Windows Installer](http://msdn.microsoft.com/library/windows/desktop/cc185688.aspx). +- Using [Windows Installer](/windows/desktop/Msi/windows-installer-portal). You do this in Visual Studio 2012 and Visual Studio 2013 by creating an InstallShield Limited Edition Project. diff --git a/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md b/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md index bef74832158eb..8c1f0f4a8ea23 100644 --- a/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md +++ b/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md @@ -19,7 +19,7 @@ There are two ways to remove an assembly from the global assembly cache (GAC): - By using the [Global Assembly Cache tool (Gacutil.exe)](../../../docs/framework/tools/gacutil-exe-gac-tool.md). You can use this option to uninstall assemblies that you've placed in the GAC during development and testing. -- By using [Windows Installer](http://msdn.microsoft.com/library/windows/desktop/cc185688.aspx). You should use this option to uninstall assemblies when testing installation packages and for production systems. +- By using [Windows Installer](/windows/desktop/Msi/windows-installer-portal). You should use this option to uninstall assemblies when testing installation packages and for production systems. ### Removing an assembly with Gacutil.exe diff --git a/docs/framework/common-client-technologies/manipulations-and-inertia-overview.md b/docs/framework/common-client-technologies/manipulations-and-inertia-overview.md index 41ed8ca8edb1c..09449b989b6e3 100644 --- a/docs/framework/common-client-technologies/manipulations-and-inertia-overview.md +++ b/docs/framework/common-client-technologies/manipulations-and-inertia-overview.md @@ -23,7 +23,7 @@ ms.assetid: dd31b89b-eab6-45a1-8d0b-11e0eb84b234 A manipulation processor does not have information about the particular element that is being manipulated. An application separately applies the changes to an application-specific element. For example, an application applies transformations to an image or redraws it to display it at its new location or with a new size or orientation. - Manipulations are designed for two-dimensional (2-D) [affine transformations](http://msdn.microsoft.com/library/ms533810\(VS.85\).aspx). These transformations include translate, rotate, and scale. + Manipulations are designed for two-dimensional (2-D) [affine transformations](/windows/desktop/gdiplus/-gdiplus-transformations-use). These transformations include translate, rotate, and scale. ### Parts of a Manipulation A manipulation is a collection of objects. This aggregate manipulation is represented by an origin point and an ellipse. The origin point is the average position of all manipulators that are manipulating an element. The ellipse has a radius that is the average distance from the origin to each of the objects. diff --git a/docs/framework/data/adonet/sql/clr-user-defined-functions.md b/docs/framework/data/adonet/sql/clr-user-defined-functions.md index 5896774ed268f..55ad7565faeda 100644 --- a/docs/framework/data/adonet/sql/clr-user-defined-functions.md +++ b/docs/framework/data/adonet/sql/clr-user-defined-functions.md @@ -6,7 +6,7 @@ ms.assetid: 1c59d9d3-6ff9-411b-8b29-b1494d80fdf1 # CLR User-Defined Functions User-defined functions are routines that can take parameters, perform calculations or other actions, and return a result. You can write user-defined functions in any Microsoft .NET Framework programming language, such as Microsoft Visual Basic .NET or Microsoft Visual C#. - For more detailed information, see [CLR User-Defined Functions](http://msdn.microsoft.com/library/ms131077.aspx). + For more detailed information, see [CLR User-Defined Functions](/sql/relational-databases/clr-integration-database-objects-user-defined-functions/clr-user-defined-functions). ## See Also [SQL Server Common Language Runtime Integration](../../../../../docs/framework/data/adonet/sql/sql-server-common-language-runtime-integration.md) diff --git a/docs/framework/data/adonet/sql/enabling-cross-database-access-in-sql-server.md b/docs/framework/data/adonet/sql/enabling-cross-database-access-in-sql-server.md index ec99e9acf9d16..d2aa541d5c345 100644 --- a/docs/framework/data/adonet/sql/enabling-cross-database-access-in-sql-server.md +++ b/docs/framework/data/adonet/sql/enabling-cross-database-access-in-sql-server.md @@ -42,7 +42,7 @@ ALTER DATABASE Database2 SET DB_CHAINING ON; |Resource|Description| |--------------|-----------------| -|[Extending Database Impersonation by Using EXECUTE AS](http://msdn.microsoft.com/library/ms188304\(SQL.105\).aspx) and [Cross DB Ownership Chaining Option](http://msdn.microsoft.com/library/ms188694.aspx)SQL Server Books Online.|Topics describe how to configure cross-database ownership chaining for an instance of SQL Server.| +|[Extending Database Impersonation by Using EXECUTE AS](http://msdn.microsoft.com/library/ms188304\(SQL.105\).aspx) and [Cross DB Ownership Chaining Option](/sql/database-engine/configure-windows/cross-db-ownership-chaining-server-configuration-option)SQL Server Books Online.|Topics describe how to configure cross-database ownership chaining for an instance of SQL Server.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/filestream-data.md b/docs/framework/data/adonet/sql/filestream-data.md index b3bb06acfd9c7..6eefeae405020 100644 --- a/docs/framework/data/adonet/sql/filestream-data.md +++ b/docs/framework/data/adonet/sql/filestream-data.md @@ -172,7 +172,7 @@ namespace FileStreamTest |[FILESTREAM Overview](http://msdn2.microsoft.com/library/bb933993\(SQL.105\).aspx)|Describes when to use FILESTREAM storage and how it integrates the SQL Server Database Engine with an NTFS file system.| |[Getting Started with FILESTREAM Storage](http://msdn.microsoft.com/library/bb933995\(SQL.105\).aspx)|Describes how to enable FILESTREAM on an instance of SQL Server, how to create a database and a table to stored FILESTREAM data, and how to manipulate rows containing FILESTREAM data.| |[Using FILESTREAM Storage in Client Applications](http://msdn.microsoft.com/library/bb933877\(SQL.105\).aspx)|Describes the Win32 API functions for working with FILESTREAM data.| -|[FILESTREAM and Other SQL Server Features](http://msdn.microsoft.com/library/bb895334\(SQL.105\).aspx)|Provides considerations, guidelines and limitations for using FILESTREAM data with other features of SQL Server.| +|[FILESTREAM and Other SQL Server Features](/sql/relational-databases/blob/filestream-compatibility-with-other-sql-server-features)|Provides considerations, guidelines and limitations for using FILESTREAM data with other features of SQL Server.| ## See Also [SQL Server Data Types and ADO.NET](../../../../../docs/framework/data/adonet/sql/sql-server-data-types.md) diff --git a/docs/framework/data/adonet/sql/index.md b/docs/framework/data/adonet/sql/index.md index d67d2fdeb0dc9..ac451633997c0 100644 --- a/docs/framework/data/adonet/sql/index.md +++ b/docs/framework/data/adonet/sql/index.md @@ -32,7 +32,7 @@ This section describes features and behaviors that are specific to the .NET Fram For complete documentation of the SQL Server Database Engine, see SQL Server Books Online for the version of SQL Server you are using. - [SQL Server Books Online](http://msdn.microsoft.com/library/ms130214.aspx) + [SQL Server Books Online](/sql/sql-server/sql-server-technical-documentation) ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/managing-permissions-with-stored-procedures-in-sql-server.md b/docs/framework/data/adonet/sql/managing-permissions-with-stored-procedures-in-sql-server.md index cca4131c711aa..9a72f01848c78 100644 --- a/docs/framework/data/adonet/sql/managing-permissions-with-stored-procedures-in-sql-server.md +++ b/docs/framework/data/adonet/sql/managing-permissions-with-stored-procedures-in-sql-server.md @@ -48,7 +48,7 @@ One method of creating multiple lines of defense around your database is to impl |Resource|Description| |--------------|-----------------| -|[Stored Procedures](http://msdn.microsoft.com/library/ms190782.aspx) and [SQL Injection](http://go.microsoft.com/fwlink/?LinkId=98234) in SQL Server Books Online|Topics describe how to create stored procedures and how SQL Injection works.| +|[Stored Procedures](/sql/relational-databases/stored-procedures/stored-procedures-database-engine) and [SQL Injection](http://go.microsoft.com/fwlink/?LinkId=98234) in SQL Server Books Online|Topics describe how to create stored procedures and how SQL Injection works.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/server-and-database-roles-in-sql-server.md b/docs/framework/data/adonet/sql/server-and-database-roles-in-sql-server.md index 2c068e9594497..cfc9422666637 100644 --- a/docs/framework/data/adonet/sql/server-and-database-roles-in-sql-server.md +++ b/docs/framework/data/adonet/sql/server-and-database-roles-in-sql-server.md @@ -21,8 +21,8 @@ All versions of SQL Server use role-based security, which allows you to assign p |Resource|Description| |--------------|-----------------| -|[Server-Level Roles](http://msdn.microsoft.com/library/ms188659.aspx) and [Permissions of Fixed Server Roles](http://msdn.microsoft.com/library/ms175892.aspx) in SQL Server Books Online|Describes fixed server roles and the permissions associated with them in SQL Server.| -|[Database-Level Roles](http://msdn.microsoft.com/library/ms189121.aspx) and [Permissions of Fixed Database Roles](http://msdn.microsoft.com/library/ms189612.aspx) in SQL Server Books Online|Describes fixed database roles and the permissions associated with them| +|[Server-Level Roles](/sql/relational-databases/security/authentication-access/server-level-roles) and [Permissions of Fixed Server Roles](http://msdn.microsoft.com/library/ms175892.aspx) in SQL Server Books Online|Describes fixed server roles and the permissions associated with them in SQL Server.| +|[Database-Level Roles](/sql/relational-databases/security/authentication-access/database-level-roles) and [Permissions of Fixed Database Roles](http://msdn.microsoft.com/library/ms189612.aspx) in SQL Server Books Online|Describes fixed database roles and the permissions associated with them| ## Database Roles and Users Logins must be mapped to database user accounts in order to work with database objects. Database users can then be added to database roles, inheriting any permission sets associated with those roles. All permissions can be granted. @@ -53,7 +53,7 @@ All versions of SQL Server use role-based security, which allows you to assign p |Resource|Description| |--------------|-----------------| |[Identity and Access Control](http://msdn.microsoft.com/library/bb510418.aspx) in SQL Server Books Online|Contains links to topics that describe principals, roles, credentials, securables and permissions.| -|[Principals](http://msdn.microsoft.com/library/ms181127.aspx) in SQL Server Books Online|Describes principals and contains links to topics that describe server and database roles.| +|[Principals](/sql/relational-databases/security/authentication-access/principals-database-engine) in SQL Server Books Online|Describes principals and contains links to topics that describe server and database roles.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/signing-stored-procedures-in-sql-server.md b/docs/framework/data/adonet/sql/signing-stored-procedures-in-sql-server.md index 887799589ce39..482a8bed81b2f 100644 --- a/docs/framework/data/adonet/sql/signing-stored-procedures-in-sql-server.md +++ b/docs/framework/data/adonet/sql/signing-stored-procedures-in-sql-server.md @@ -46,7 +46,7 @@ If the module needs additional server-level permissions: |Resource|Description| |--------------|-----------------| |[Module Signing](http://go.microsoft.com/fwlink/?LinkId=98590) in SQL Server Books Online|Describes module signing, providing a sample scenario and links to the relevant Transact-SQL topics.| -|[Signing Stored Procedures with a Certificate](http://msdn.microsoft.com/library/bb283630.aspx) in SQL Server Books Online|Provides a tutorial for signing a stored procedure with a certificate.| +|[Signing Stored Procedures with a Certificate](/sql/relational-databases/tutorial-signing-stored-procedures-with-a-certificate) in SQL Server Books Online|Provides a tutorial for signing a stored procedure with a certificate.| ## See Also [Securing ADO.NET Applications](../../../../../docs/framework/data/adonet/securing-ado-net-applications.md) diff --git a/docs/framework/data/adonet/sql/table-valued-parameters.md b/docs/framework/data/adonet/sql/table-valued-parameters.md index 5ad0c2457b80e..bc319fe202edc 100644 --- a/docs/framework/data/adonet/sql/table-valued-parameters.md +++ b/docs/framework/data/adonet/sql/table-valued-parameters.md @@ -71,7 +71,7 @@ INSERT INTO dbo.Categories (CategoryID, CategoryName) ## Limitations of Table-Valued Parameters There are several limitations to table-valued parameters: -- You cannot pass table-valued parameters to [CLR user-defined functions](http://msdn.microsoft.com/library/ms131077.aspx). +- You cannot pass table-valued parameters to [CLR user-defined functions](/sql/relational-databases/clr-integration-database-objects-user-defined-functions/clr-user-defined-functions). - Table-valued parameters can only be indexed to support UNIQUE or PRIMARY KEY constraints. SQL Server does not maintain statistics on table-valued parameters. diff --git a/docs/framework/deployment/deployment-guide-for-developers.md b/docs/framework/deployment/deployment-guide-for-developers.md index 55c93a6978964..897a806e74619 100644 --- a/docs/framework/deployment/deployment-guide-for-developers.md +++ b/docs/framework/deployment/deployment-guide-for-developers.md @@ -41,7 +41,7 @@ For download links, see the section [Redistributable Packages](#redistributable- - The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and its point releases are built incrementally on the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)]. When you install the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] or its point releases on a system that has the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] installed, the version 4 assemblies are replaced with newer versions. -- If you are referencing a Microsoft [out-of-band package](http://msdn.microsoft.com/library/dn151288\(v=vs.110\).aspx) in your app, the assembly will be included in the app package. +- If you are referencing a Microsoft [out-of-band package](../get-started/the-net-framework-and-out-of-band-releases.md) in your app, the assembly will be included in the app package. - You must have administrator privileges to install the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and its point releases. diff --git a/docs/framework/deployment/guide-for-administrators.md b/docs/framework/deployment/guide-for-administrators.md index 91f1401b2f3a9..15bf93b9fce89 100644 --- a/docs/framework/deployment/guide-for-administrators.md +++ b/docs/framework/deployment/guide-for-administrators.md @@ -246,7 +246,7 @@ This step-by-step article describes how a system administrator can deploy the [! - [URL moniker error codes](http://msdn.microsoft.com/library/ms775145.aspx) -- [WinHttp error codes](http://msdn.microsoft.com/library/aa383770.aspx) +- [WinHttp error codes](/windows/desktop/WinHttp/error-messages) Other error codes: diff --git a/docs/framework/develop-client-apps.md b/docs/framework/develop-client-apps.md index 0f4f3ac960c4c..bb1f6d2cffb38 100644 --- a/docs/framework/develop-client-apps.md +++ b/docs/framework/develop-client-apps.md @@ -43,7 +43,7 @@ Describes how to create applications for Windows 10 that you can make available [.NET for UWP apps](https://msdn.microsoft.com/library/windows/apps/mt185501.aspx) Describes the .NET Framework support for Store apps, which can be deployed to Windows computers and devices. -[.NET API for Windows Phone Silverlight](https://docs.microsoft.com/en-us/previous-versions/windows/apps/jj207211\(v=vs.105\)) +[.NET API for Windows Phone Silverlight](https://docs.microsoft.com/previous-versions/windows/apps/jj207211\(v=vs.105\)) Lists the .NET Framework APIs you can use for building apps with Windows Phone Silverlight. [Developing for Multiple Platforms](../../docs/standard/cross-platform/index.md) diff --git a/docs/framework/install/guide-for-developers.md b/docs/framework/install/guide-for-developers.md index ff45dd3a91673..a28111ec1e2d6 100644 --- a/docs/framework/install/guide-for-developers.md +++ b/docs/framework/install/guide-for-developers.md @@ -37,7 +37,7 @@ Use the following table for quick links, or read further for details. To view th |**4.7**|[NET Framework 4.7 Developer Pack](http://go.microsoft.com/fwlink/?LinkId=825319)|[Download page for 4.7 web installer](http://go.microsoft.com/fwlink/?LinkId=825299)

[Download page for 4.7 offline installer](http://go.microsoft.com/fwlink/?LinkId=825303)|Included in:
Windows 10 Creators Update

You can install on:
Windows 10 Anniversary Update
Windows 8.1 and earlier
Windows Server 2016 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))|| |**4.6.2**|[NET Framework 4.6.2 Developer Pack](http://go.microsoft.com/fwlink/?LinkId=780617)|[Download page for 4.6.2 web installer](http://go.microsoft.com/fwlink/?LinkId=780597)

[Download page for 4.6.2 offline installer](http://go.microsoft.com/fwlink/?LinkId=780601)|Included in:
Windows 10 Anniversary Update

You can install on:
Windows 10 November Update
Windows 10
Windows 8.1 and earlier
Windows Server 2012 R2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| |**4.6.1**|[NET Framework 4.6.1 Developer Pack](http://go.microsoft.com/fwlink/?LinkId=690706)|[Download page for 4.6.1 web installer](http://go.microsoft.com/fwlink/?LinkId=671729)

[Download page for 4.6.1 offline installer](http://go.microsoft.com/fwlink/?LinkId=671744)|You can install on:
Windows 10
Windows 8.1 and earlier
Windows Server 2012 R2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| -|**4.6**|Included in [!INCLUDE[vs_dev14](../../../includes/vs-dev14-md.md)]. For more information, see [Welcome to Visual Studio 2015](http://msdn.microsoft.com/library/dd831853\(v=vs.140\).aspx).

[Microsoft .NET Framework 4.6 targeting pack](http://go.microsoft.com/fwlink/?LinkId=528261)|[Download page for 4.6 web installer](http://go.microsoft.com/fwlink/?LinkId=528259)

[Download page for 4.6 offline installer](http://go.microsoft.com/fwlink/?LinkId=528233)|Included in:
Windows 10
[!INCLUDE[vs_dev14](../../../includes/vs-dev14-md.md)]

You can also install on:
Windows 8.1 and earlier
Windows Server 2012 R2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| +|**4.6**|Included in [!INCLUDE[vs_dev14](../../../includes/vs-dev14-md.md)]. For more information, see [Welcome to Visual Studio 2015](/visualstudio/welcome-to-visual-studio).

[Microsoft .NET Framework 4.6 targeting pack](http://go.microsoft.com/fwlink/?LinkId=528261)|[Download page for 4.6 web installer](http://go.microsoft.com/fwlink/?LinkId=528259)

[Download page for 4.6 offline installer](http://go.microsoft.com/fwlink/?LinkId=528233)|Included in:
Windows 10
[!INCLUDE[vs_dev14](../../../includes/vs-dev14-md.md)]

You can also install on:
Windows 8.1 and earlier
Windows Server 2012 R2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| |**4.5.2**|[Microsoft .NET Framework 4.5.2 Developer Pack](http://go.microsoft.com/fwlink/?LinkId=397702)

For use with Visual Studio 2013, Visual Studio 2012, or other IDEs|[Download page for 4.5.2 web installer](http://go.microsoft.com/fwlink/p/?LinkId=397703)

[Download page for 4.5.2 offline installer](http://go.microsoft.com/fwlink/p/?LinkId=397706)|You can install on:
Windows 8.1 and earlier
Windows Server 2012 R2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| |**4.5.1**|[Microsoft .NET Framework 4.5.1 Developer Pack](http://go.microsoft.com/fwlink/?LinkId=324213)

For use with Visual Studio 2012 or other IDEs|[Download page for 4.5.1 web installer](http://go.microsoft.com/fwlink/p/?LinkId=310158)

[Download page for 4.5.1 offline installer](http://go.microsoft.com/fwlink/p/?LinkId=310159)|Included in:
[!INCLUDE[win81](../../../includes/win81-md.md)]
Windows Server 2012 R2
[Visual Studio 2013](http://go.microsoft.com/fwlink/?LinkID=325532)

You can also install on:
[!INCLUDE[win8](../../../includes/win8-md.md)] and earlier
[!INCLUDE[winserver8](../../../includes/winserver8-md.md)] and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| |**4.5**|Included in Visual Studio 2012

Also available as part of the [Windows 8 SDK](http://msdn.microsoft.com/windows/hardware/hh852363)|[Download page for 4.5 web installer](http://go.microsoft.com/fwlink/p/?LinkId=245484)|Included in:
[!INCLUDE[win8](../../../includes/win8-md.md)]
[!INCLUDE[winserver8](../../../includes/winserver8-md.md)]
Visual Studio 2012

You can also install on:
Windows 7 and earlier
Windows Server 2008 SP2 and earlier
(for a full list, see [system requirements](~/docs/framework/get-started/system-requirements.md))| diff --git a/docs/framework/interop/configure-net-framework-based-com-components-for-reg.md b/docs/framework/interop/configure-net-framework-based-com-components-for-reg.md index 1089184c1e638..6ddda18724d5f 100644 --- a/docs/framework/interop/configure-net-framework-based-com-components-for-reg.md +++ b/docs/framework/interop/configure-net-framework-based-com-components-for-reg.md @@ -31,7 +31,7 @@ Registration-free activation for .NET Framework-based components is only slightl ``` - For information about manifest elements and their attributes, see [Application Manifests](https://msdn.microsoft.com/library/windows/desktop/aa374191.aspx). + For information about manifest elements and their attributes, see [Application Manifests](/windows/desktop/SbsCs/application-manifests). 3. Identify the owner of the manifest. In the following example, `myComApp` version 1 owns the manifest file. @@ -71,7 +71,7 @@ Registration-free activation for .NET Framework-based components is only slightl 5. Save and name the manifest file. The name of an application manifest is the name of the assembly executable followed by the .manifest extension. For example, the application manifest file name for myComApp.exe is myComApp.exe.manifest. - You can install an application manifest in the same directory as the COM application. Alternatively, you can add it as a resource to the application's .exe file. For additional information, For more information, see [About Side-by-Side Assemblies](https://msdn.microsoft.com/library/windows/desktop/ff951640.aspx). + You can install an application manifest in the same directory as the COM application. Alternatively, you can add it as a resource to the application's .exe file. For additional information, For more information, see [About Side-by-Side Assemblies](/windows/desktop/SbsCs/about-side-by-side-assemblies-). #### To create a component manifest diff --git a/docs/framework/interop/registration-free-com-interop.md b/docs/framework/interop/registration-free-com-interop.md index 108e3aa3485a0..d6c9c15af88d3 100644 --- a/docs/framework/interop/registration-free-com-interop.md +++ b/docs/framework/interop/registration-free-com-interop.md @@ -39,11 +39,11 @@ Registration-free COM interop activates a component without using the Windows re ### Configuring COM components for registration-free activation -1. For a COM component to participate in registration-free activation, it must be deployed as a side-by-side assembly. Side-by-side assemblies are unmanaged assemblies. For more information, see [Using Side-by-side Assemblies](https://msdn.microsoft.com/library/windows/desktop/aa376618.aspx). +1. For a COM component to participate in registration-free activation, it must be deployed as a side-by-side assembly. Side-by-side assemblies are unmanaged assemblies. For more information, see [Using Side-by-side Assemblies](/windows/desktop/SbsCs/using-side-by-side-assemblies). To use COM side-by-side assemblies, a .NET-based application developer must provide an application manifest, which contains the binding and activation information. Support for unmanaged side-by-side assemblies is built into the Windows XP operating system. The COM runtime, supported by the operating system, scans an application manifest for activation information when the component being activated is not in the registry. - Registration-free activation is optional for COM components installed on Windows XP. For detailed instructions on adding a side-by-side assembly to an application, see [Using Side-by-side Assemblies](https://msdn.microsoft.com/library/windows/desktop/aa376618.aspx). + Registration-free activation is optional for COM components installed on Windows XP. For detailed instructions on adding a side-by-side assembly to an application, see [Using Side-by-side Assemblies](/windows/desktop/SbsCs/using-side-by-side-assemblies). > [!NOTE] > Side-by-side execution is a .NET Framework feature that enables multiple versions of the runtime, and multiple versions of applications and components that use a version of the runtime, to run on the same computer at the same time. Side-by-side execution and side-by-side assemblies are different mechanisms for providing side-by-side functionality. diff --git a/docs/framework/migration-guide/mitigation-path-normalization.md b/docs/framework/migration-guide/mitigation-path-normalization.md index 00cee0959b95e..b66de5b008ede 100644 --- a/docs/framework/migration-guide/mitigation-path-normalization.md +++ b/docs/framework/migration-guide/mitigation-path-normalization.md @@ -22,7 +22,7 @@ Starting with apps the target the [!INCLUDE[net_v462](../../../includes/net-v46 ## The changes Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], path normalization has changed in the following ways: -- The runtime defers to the operating system's [GetFullPathName](https://msdn.microsoft.com/library/windows/desktop/aa364963\(v=vs.85\).aspx) function to normalize paths. +- The runtime defers to the operating system's [GetFullPathName](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea) function to normalize paths. - Normalization no longer involves trimming the end of directory segments (such as a space at the end of a directory name). diff --git a/docs/framework/migration-guide/net-framework-4-migration-issues.md b/docs/framework/migration-guide/net-framework-4-migration-issues.md index 52ab552e1d3ad..57f19ac36f4fb 100644 --- a/docs/framework/migration-guide/net-framework-4-migration-issues.md +++ b/docs/framework/migration-guide/net-framework-4-migration-issues.md @@ -116,7 +116,7 @@ Namespace: ; assembly: mscorlib (in mscorlib.dll) | **Assembly loading** | To prevent redundant loading of assemblies and to save virtual address space, the CLR now loads assemblies by using only the Win32 `MapViewOfFile` function. It no longer also calls the `LoadLibrary` function.

This change affects diagnostic applications in the following ways:

* A will no longer contain any modules from a class library (.dll file), as obtained from a call to `Process.GetCurrentProcess().Modules`.
* Win32 applications that use the `EnumProcessModules` function will not see all managed modules listed. | None. | | **Declaring type** | The property now correctly returns null when the type does not have a declaring type. | None. | | **Delegates** | A delegate now throws an instead of a when a null value is passed to the delegate's constructor. | Ensure that any exception handling catches . | -| **Global assembly cache location change** | For .NET Framework 4 assemblies, the global assembly cache has been moved from the Windows directory (%WINDIR%) to the Microsoft.Net subdirectory (*%WINDIR%\\Microsoft.Net*). Assemblies from earlier versions remain in the older directory.

The unmanaged [ASM_CACHE_FLAGS](https://msdn.microsoft.com/library/ms231621(v=vs.100).aspx) enumeration contains the new `ASM_CACHE_ROOT_EX` flag. This flag gets the cache location for .NET Framework 4 assemblies, which can be obtained by the [GetCachePath](/dotnet/framework/unmanaged-api/fusion/getcachepath-function) function. | None, assuming that applications do not use explicit paths to assemblies, which is not a recommended practice. | +| **Global assembly cache location change** | For .NET Framework 4 assemblies, the global assembly cache has been moved from the Windows directory (%WINDIR%) to the Microsoft.Net subdirectory (*%WINDIR%\\Microsoft.Net*). Assemblies from earlier versions remain in the older directory.

The unmanaged [ASM_CACHE_FLAGS](../unmanaged-api/fusion/asm-cache-flags-enumeration.md) enumeration contains the new `ASM_CACHE_ROOT_EX` flag. This flag gets the cache location for .NET Framework 4 assemblies, which can be obtained by the [GetCachePath](../unmanaged-api/fusion/getcachepath-function.md) function. | None, assuming that applications do not use explicit paths to assemblies, which is not a recommended practice. | | **Global assembly cache tool** | The [Gacutil.exe (Global Assembly Cache Tool)](https://msdn.microsoft.com/library/ex0ss12c(v=vs.100).aspx) no longer supports the shell plugin viewer. | None. | ### Interoperability @@ -125,9 +125,9 @@ Namespace: ; assembly: mscorlib (in mscorli | Feature | Differences from 3.5 SP1 | Recommended changes | | ------- | ------------------------ | ------------------- | -| **Buffer length** (unmanaged API) | To save memory, the functionality for the `pBufferLengthOffset` parameter for the [ICorProfilerInfo2::GetStringLayout](/dotnet/framework/unmanaged-api/profiling/icorprofilerinfo2-getstringlayout-method) method has been changed to match the `pStringLengthOffset` parameter. Both parameters now point to the offset location of the string's length. Buffer length has been removed from the representation of the string class. | Remove any dependency on the buffer length. | +| **Buffer length** (unmanaged API) | To save memory, the functionality for the `pBufferLengthOffset` parameter for the [ICorProfilerInfo2::GetStringLayout](../unmanaged-api/profiling/icorprofilerinfo2-getstringlayout-method.md) method has been changed to match the `pStringLengthOffset` parameter. Both parameters now point to the offset location of the string's length. Buffer length has been removed from the representation of the string class. | Remove any dependency on the buffer length. | | **JIT debugging** | To simplify registration for just-in-time (JIT) debugging, the .NET Framework debugger now uses only the AeDebug registry key, which controls the JIT debugging behavior for native code. This change results in the following:

* You can no longer register two different debuggers for managed and native code.
* You can no longer start the debugger automatically for a non-interactive process, but you can prompt the user for an interactive process.
* You are no longer notified when the debugger fails to start, or when there is no registered debugger that should be started.
* Auto-launch policies that depend on the interactivity of the application are no longer supported. | Adjust debugging operations as required. | -| **Platform invoke** | To improve performance in interoperability with unmanaged code, incorrect calling conventions in a platform invoke now cause the application to fail. In previous versions, the marshaling layer resolved these errors up the stack. | Debugging your applications in Microsoft Visual Studio 2010 will alert you to these errors so you can correct them.

If you have binaries that cannot be updated, you can include the [\](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element) element in your application's configuration file to enable calling errors to be resolved up the stack as in earlier versions. However, this may affect the performance of your application. | +| **Platform invoke** | To improve performance in interoperability with unmanaged code, incorrect calling conventions in a platform invoke now cause the application to fail. In previous versions, the marshaling layer resolved these errors up the stack. | Debugging your applications in Microsoft Visual Studio 2010 will alert you to these errors so you can correct them.

If you have binaries that cannot be updated, you can include the [\](../configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md) element in your application's configuration file to enable calling errors to be resolved up the stack as in earlier versions. However, this may affect the performance of your application. | | **Removed interfaces** (unmanaged API) | To avoid developer confusion, the following interfaces were removed, because they did not provide any useful run-time scenarios, and the CLR did not provide or accept any implementations:

* **INativeImageINativeImageDependency**
* **INativeImageInstallInfo**
* **INativeImageEvaluate**
* **INativeImageConverter**
* **ICorModule**
* **IMetaDataConverter** | None. | ## Data diff --git a/docs/framework/migration-guide/versions-and-dependencies.md b/docs/framework/migration-guide/versions-and-dependencies.md index 8f7c66e3b44d4..e8826b35235a1 100644 --- a/docs/framework/migration-guide/versions-and-dependencies.md +++ b/docs/framework/migration-guide/versions-and-dependencies.md @@ -33,7 +33,7 @@ Each version of the .NET Framework contains the common language runtime (CLR), t |4.5.2

[New features](../whats-new/index.md#whats-new-in-the-net-framework-452)|4|-|+ 8.1
+ 8
+ 7
+ Vista|+ 2012 R2
+ 2012
+ 2008 R2 SP1
+ 2008 SP2|Use `Release` DWORD:

379893

(see [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md))| |4.5.1

[New features](../whats-new/index.md#whats-new-in-the-net-framework-451)|4|2013|✓ 8.1
+ 8
+ 7
+ Vista|✓ 2012 R2
+ 2012
+ 2008 R2 SP1
+ 2008 SP2|Use `Release` DWORD:

- 378675 (Windows 8.1)
- 378758 (all other)

(see [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md))| |4.5

[New features](../whats-new/index.md#whats-new-in-the-net-framework-45)|4|2012|✓ 8
+ 7
+ Vista|✓ 2012
+ 2008 R2 SP1
+ 2008 SP2|Use `Release` DWORD:

378389

(see [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md))| -|4

[New features](http://msdn.microsoft.com/library/ms171868\(v=vs.100\).aspx)|4|2010|+ 7
+ Vista|+ 2008 R2 SP1
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| +|4

[New features](../whats-new/index.md)|4|2010|+ 7
+ Vista|+ 2008 R2 SP1
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |3.5

[New features](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2008/ms171868\(v=vs.90\))|2.0|2008|✓ 10\*
✓ 8.1\*
✓ 8\*
✓ 7
+ Vista|✓2008 R2 SP1\*
+ 2012 R2\*
+ 2012\*
+ 2008 SP2
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |3.0

New:
WPF, WCF, WF, CardSpace|2.0|-|✓ Vista|✓ 2008 R2 SP1*
✓ 2008 SP2\*
+ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| |2.0

[New features](https://docs.microsoft.com/previous-versions/dotnet/netframework-2.0/ms229284\(v%3dvs.80\))|2.0|2005|-|✓ 2008 R2 SP1
✓ 2008 SP2
✓ 2003|See [instructions](../../../docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md)| diff --git a/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md b/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md index 33233d690d054..a2dce6e52ff5a 100644 --- a/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md +++ b/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md @@ -211,9 +211,9 @@ ms.author: "ronpet" || || - is supported, but it throws an exception in some scenarios, such as when it is used with [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) or byref variants. + is supported, but it throws an exception in some scenarios, such as when it is used with [IDispatch](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/nn-oaidl-idispatch) or byref variants. - Deprecated APIs for [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) support: + Deprecated APIs for [IDispatch](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/nn-oaidl-idispatch) support: |Type|Member| |----------|------------| @@ -312,7 +312,7 @@ ms.author: "ronpet" - `BStr` - - [IUnknown](http://msdn.microsoft.com/library/windows/desktop/ms680509.aspx) + - [IUnknown](/windows/desktop/api/unknwn/nn-unknwn-iunknown) However, .NET Native doesn't support the following: @@ -320,7 +320,7 @@ ms.author: "ronpet" - Implementing the interface on a managed type -- Implementing the [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) interface on a managed type through the attribute. However, note that you can't call COM objects through `IDispatch`, and your managed object can't implement `IDispatch`. +- Implementing the [IDispatch](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/nn-oaidl-idispatch) interface on a managed type through the attribute. However, note that you can't call COM objects through `IDispatch`, and your managed object can't implement `IDispatch`. Using reflection to invoke a platform invoke method isn't supported. You can work around this limitation by wrapping the method call in another method and using reflection to call the wrapper instead. diff --git a/docs/framework/network-programming/network-programming-samples.md b/docs/framework/network-programming/network-programming-samples.md index 39be1345a5a76..fdc0df778d211 100644 --- a/docs/framework/network-programming/network-programming-samples.md +++ b/docs/framework/network-programming/network-programming-samples.md @@ -22,7 +22,7 @@ This section contains descriptions and links to downloadable network programming [HttpListener Technology Sample](https://msdn.microsoft.com/en-us/library/y7cbb2y2(v=vs.85).aspx) Shows how to process HTTP requests from within an application. - [HttpListener ASPX Host Application Sample](https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2008/dd767375(v%3dvs.90)) + [HttpListener ASPX Host Application Sample](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2008/dd767375(v%3dvs.90)) Demonstrates how to use the features of the class to create an HTTP server that routes calls to a hosted ASP.NET application. [Mailer Technology Sample](https://msdn.microsoft.com/en-us/library/whw7xbk2(v=vs.85).aspx) diff --git a/docs/framework/security/how-to-debug-claims-aware-applications-and-services-using-wif-tracing.md b/docs/framework/security/how-to-debug-claims-aware-applications-and-services-using-wif-tracing.md index ec7eba839f38f..14218aac601aa 100644 --- a/docs/framework/security/how-to-debug-claims-aware-applications-and-services-using-wif-tracing.md +++ b/docs/framework/security/how-to-debug-claims-aware-applications-and-services-using-wif-tracing.md @@ -71,7 +71,7 @@ manager: "mbaldwin" ``` -3. The above configuration instructs WIF to generate verbose trace events and log them into *WIFTrace.e2e* file. For a complete list of values for the **switchValue** switch, refer to the Trace Level table found in the following topic: [Configuring Tracing](http://msdn.microsoft.com/library/ms733025.aspx). +3. The above configuration instructs WIF to generate verbose trace events and log them into *WIFTrace.e2e* file. For a complete list of values for the **switchValue** switch, refer to the Trace Level table found in the following topic: [Configuring Tracing](../wcf/diagnostics/tracing/configuring-tracing.md). ## Step 2 – Analyze WIF Trace Files Using Trace Viewer Tool In this step, you will use the Trace Viewer Tool (SvcTraceViewer.exe) to analyze WIF trace logs. @@ -103,4 +103,4 @@ manager: "mbaldwin" ## Related Items -- [Using Service Trace Viewer for Viewing Correlated Traces and Troubleshooting](http://msdn.microsoft.com/library/aa751795.aspx) +- [Using Service Trace Viewer for Viewing Correlated Traces and Troubleshooting](../wcf/diagnostics/tracing/using-service-trace-viewer-for-viewing-correlated-traces-and-troubleshooting.md) diff --git a/docs/framework/tools/signtool-exe.md b/docs/framework/tools/signtool-exe.md index 0d4e82110e614..2a8e058d1f509 100644 --- a/docs/framework/tools/signtool-exe.md +++ b/docs/framework/tools/signtool-exe.md @@ -91,7 +91,7 @@ signtool [command] [options] [file_name | ...] |`/u` *Usage*|Specifies the enhanced key usage (EKU) that must be present in the signing certificate. The usage value can be specified by OID or string. The default usage is "Code Signing" (1.3.6.1.5.5.7.3.3).| |`/uw`|Specifies usage of "Windows System Component Verification" (1.3.6.1.4.1.311.10.3.6).| - For usage examples, see [Using SignTool to Sign a File](http://msdn.microsoft.com/library/windows/desktop/aa388170.aspx). + For usage examples, see [Using SignTool to Sign a File](/windows/desktop/SecCrypto/using-signtool-to-sign-a-file). ## TimeStamp Command Options @@ -105,7 +105,7 @@ signtool [command] [options] [file_name | ...] |`/tp` *index*|Time stamps the signature at *index*.| |`/tr` *URL*|Specifies the URL of the RFC 3161 time stamp server. The file being time stamped must have previously been signed. Either the `/tr` or the `/t` option is required.| - For a usage example, see [Adding Time Stamps to Previously Signed Files](http://msdn.microsoft.com/library/windows/desktop/aa375542.aspx). + For a usage example, see [Adding Time Stamps to Previously Signed Files](/windows/desktop/SecCrypto/adding-time-stamps-to-previously-signed-files). ## Verify Command Options @@ -122,7 +122,7 @@ signtool [command] [options] [file_name | ...] |`/ds` *Index*|Verifies the signature at a specified position.| |`/hash` (`SHA1`|`SHA256`)|Specifies an optional hash algorithm to use when searching for a file in a catalog.| |`/kp`|Specifies that verification should be performed with the kernel-mode driver signing policy.| -|`/ms`|Uses multiple verification semantics. This is the default behavior of a [WinVerifyTrust](http://msdn.microsoft.com/library/windows/desktop/aa388208.aspx) call on [!INCLUDE[win8](../../../includes/win8-md.md)] and above.| +|`/ms`|Uses multiple verification semantics. This is the default behavior of a [WinVerifyTrust](/windows/desktop/api/wintrust/nf-wintrust-winverifytrust) call on [!INCLUDE[win8](../../../includes/win8-md.md)] and above.| |`/o` *Version*|Verifies the file by operating system version. *Version* has the following form: *PlatformID*:*VerMajor*.*VerMinor*.*BuildNumber*. *PlatformID* represents the underlying value of a enumeration member. **Important:** The use of the `/o` switch is recommended. If `/o` is not specified, SignTool.exe may return unexpected results. For example, if you do not include the `/o` switch, system catalogs that validate correctly on an older operating system may not validate correctly on a newer operating system.| |`/p7`|Verifies PKCS #7 files. No existing policies are used for PKCS #7 validation. The signature is checked and a chain is built for the signing certificate.| |`/pa`|Specifies that the Default Authenticode Verification Policy should be used. If the `/pa` option is not specified, Sign Tool uses the Windows Driver Verification Policy. This option cannot be used with the `catdb` options.| @@ -131,7 +131,7 @@ signtool [command] [options] [file_name | ...] |`/r` *RootSubjectName*|Specifies the name of the subject of the root certificate that the signing certificate must chain to. This value can be a substring of the entire subject name of the root certificate.| |`/tw`|Specifies that a warning should be generated if the signature is not time stamped.| - For usage examples, see [Using SignTool to Verify a File Signature](http://msdn.microsoft.com/library/windows/desktop/aa388171.aspx). + For usage examples, see [Using SignTool to Verify a File Signature](/windows/desktop/SecCrypto/using-signtool-to-verify-a-file-signature). ## Return Value Sign Tool returns one of the following exit codes when it terminates. diff --git a/docs/framework/unmanaged-api/authenticode/axl-authenticode-signer-info-structure.md b/docs/framework/unmanaged-api/authenticode/axl-authenticode-signer-info-structure.md index bd8ac3f8440dc..417b675e1383e 100644 --- a/docs/framework/unmanaged-api/authenticode/axl-authenticode-signer-info-structure.md +++ b/docs/framework/unmanaged-api/authenticode/axl-authenticode-signer-info-structure.md @@ -32,7 +32,7 @@ typedef struct _AXL_AUTHENTICODE_SIGNER_INFO { |`pwszHash`|The hash.| |`pwszDescription`|The description.| |`pwszDescriptionUrl`|The URL of the description.| -|`pChainContext`|The chain context of the signer. See the [CERT_CONTEXT](http://msdn.microsoft.com/library/windows/desktop/aa377189.aspx) structure.| +|`pChainContext`|The chain context of the signer. See the [CERT_CONTEXT](/windows/desktop/api/wincrypt/ns-wincrypt-_cert_context) structure.| ## See Also [Authenticode](../../../../docs/framework/unmanaged-api/authenticode/index.md) diff --git a/docs/framework/unmanaged-api/authenticode/axl-authenticode-timestamper-info-structure.md b/docs/framework/unmanaged-api/authenticode/axl-authenticode-timestamper-info-structure.md index 4738758af944b..3c4c3313892f7 100644 --- a/docs/framework/unmanaged-api/authenticode/axl-authenticode-timestamper-info-structure.md +++ b/docs/framework/unmanaged-api/authenticode/axl-authenticode-timestamper-info-structure.md @@ -28,7 +28,7 @@ typedef struct _AXL_AUTHENTICODE_SIGNER_INFO { |`dwError`|The error code.| |`algHash`|The hash algorithm.| |`ftTimestamp`|The time of the time stamp.| -|`pChainContext`|The time stamper’s chain context. See the [CERT_CONTEXT](http://msdn.microsoft.com/library/windows/desktop/aa377189.aspx) structure.| +|`pChainContext`|The time stamper’s chain context. See the [CERT_CONTEXT](/windows/desktop/api/wincrypt/ns-wincrypt-_cert_context) structure.| ## See Also [Authenticode](../../../../docs/framework/unmanaged-api/authenticode/index.md) diff --git a/docs/framework/unmanaged-api/authenticode/axlgetissuerpublickeyhash-function.md b/docs/framework/unmanaged-api/authenticode/axlgetissuerpublickeyhash-function.md index e6e90d2912d18..46980b1621e61 100644 --- a/docs/framework/unmanaged-api/authenticode/axlgetissuerpublickeyhash-function.md +++ b/docs/framework/unmanaged-api/authenticode/axlgetissuerpublickeyhash-function.md @@ -25,7 +25,7 @@ HRESULT _AxlGetIssuerPublicKeyHash ( #### Parameters `pChainContext` - [in] The CSP public key blob. See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + [in] The CSP public key blob. See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. `ppwszPublicKeyHash` [out] A pointer to WCHAR * to receive the hex-encoded public key token. diff --git a/docs/framework/unmanaged-api/authenticode/axlrsakeyvaluetopublickeytoken-function.md b/docs/framework/unmanaged-api/authenticode/axlrsakeyvaluetopublickeytoken-function.md index 8c6751d03427c..63fc8401f3d67 100644 --- a/docs/framework/unmanaged-api/authenticode/axlrsakeyvaluetopublickeytoken-function.md +++ b/docs/framework/unmanaged-api/authenticode/axlrsakeyvaluetopublickeytoken-function.md @@ -27,10 +27,10 @@ HRESULT _AxlRSAKeyValueToPublicKeyToken ( ### Parameters `pModulusBlob` - [in] The base64-encoded Modulus blob (from the \ element). See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + [in] The base64-encoded Modulus blob (from the \ element). See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. `pExponentBlob` - [in] The base64-encoded Exponent blob (from the \ element). See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + [in] The base64-encoded Exponent blob (from the \ element). See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. `ppwszPublicKeyToken` [out] A pointer to WCHAR * to receive the hex-encoded public key token. diff --git a/docs/framework/unmanaged-api/authenticode/certtimestampauthenticodelicense-function.md b/docs/framework/unmanaged-api/authenticode/certtimestampauthenticodelicense-function.md index ef71a7267f4b1..6da26ef1c96df 100644 --- a/docs/framework/unmanaged-api/authenticode/certtimestampauthenticodelicense-function.md +++ b/docs/framework/unmanaged-api/authenticode/certtimestampauthenticodelicense-function.md @@ -26,13 +26,13 @@ HRESULT CertTimestampAuthenticodeLicense ( #### Parameters `pSignedLicenseBlob` - [in] The signed Authenticode XrML license to be time-stamped. See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + [in] The signed Authenticode XrML license to be time-stamped. See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. `pwszTimestampURI` [in] The time-stamp server's URI. `pTimestampSignatureBlob` - [out] A pointer to CRYPT_DATA_BLOB to receive the base64-encoded time-stamp signature. It is the caller's responsibility to free `pTimestampSignatureBlob`->`pbData` with `HepFree()` after use. See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + [out] A pointer to CRYPT_DATA_BLOB to receive the base64-encoded time-stamp signature. It is the caller's responsibility to free `pTimestampSignatureBlob`->`pbData` with `HepFree()` after use. See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. ## Remarks The time-stamp signature is actually a PKCS #7 SignedData message whose content is the binary form of the SignatureValue from the license's signature. Basically, this acts as a counter-signature of the license. diff --git a/docs/framework/unmanaged-api/authenticode/certverifyauthenticodelicense-function.md b/docs/framework/unmanaged-api/authenticode/certverifyauthenticodelicense-function.md index e2defb9181c02..f8338414ece7c 100644 --- a/docs/framework/unmanaged-api/authenticode/certverifyauthenticodelicense-function.md +++ b/docs/framework/unmanaged-api/authenticode/certverifyauthenticodelicense-function.md @@ -29,7 +29,7 @@ HRESULT CertVerifyAuthenticodeLicense ( `pLicenseBlob` [in] The Authenticode XrML license to be verified. - See the [CRYPTOAPI_BLOB](http://msdn.microsoft.com/library/windows/desktop/aa380238.aspx) structure. + See the [CRYPTOAPI_BLOB](/windows/desktop/api/dpapi/ns-dpapi-_cryptoapi_blob) structure. `dwFlags` [in] Optional. A combination of following values: diff --git a/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptioncontextrecord-method.md b/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptioncontextrecord-method.md index cca3c6e5dba43..900a31efb49e0 100644 --- a/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptioncontextrecord-method.md +++ b/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptioncontextrecord-method.md @@ -16,7 +16,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # ICLRDataTarget3::GetExceptionContextRecord Method -Called by the common language runtime (CLR) data access services to retrieve the context record associated with the target process. For example, for a dump target, this would be equivalent to the context record passed in via the `ExceptionParam` argument to the [MiniDumpWriteDump](http://msdn.microsoft.com/library/windows/desktop/ms680360\(v=vs.85\).aspx) function in the Windows Debug Help Library (DbgHelp). +Called by the common language runtime (CLR) data access services to retrieve the context record associated with the target process. For example, for a dump target, this would be equivalent to the context record passed in via the `ExceptionParam` argument to the [MiniDumpWriteDump](/windows/desktop/api/minidumpapiset/nf-minidumpapiset-minidumpwritedump) function in the Windows Debug Help Library (DbgHelp). ## Syntax @@ -36,7 +36,7 @@ HRESULT GetExceptionContextRecord( [out] A pointer to a `ULONG32` type that receives the number of bytes actually written to the buffer. `buffer` - [out] A pointer to a memory buffer that receives a copy of the context record. The exception record is returned as a [CONTEXT](http://msdn.microsoft.com/library/windows/desktop/ms679284\(v=vs.85\).aspx) type. + [out] A pointer to a memory buffer that receives a copy of the context record. The exception record is returned as a [CONTEXT](/windows/desktop/api/winnt/ns-winnt-_arm64_nt_context) type. ## Return Value The return value is `S_OK` on success, or a failure `HRESULT` code on failure. The `HRESULT` codes can include but are not limited to the following: @@ -48,7 +48,7 @@ HRESULT GetExceptionContextRecord( |`HRESULT_FROM_WIN32(ERROR_BAD_LENGTH)`|The input buffer size is not large enough to accommodate the context record.| ## Remarks - [CONTEXT](http://msdn.microsoft.com/library/windows/desktop/ms679284\(v=vs.85\).aspx) is a platform-specific structure defined in headers provided by the Windows SDK. + [CONTEXT](/windows/desktop/api/winnt/ns-winnt-_arm64_nt_context) is a platform-specific structure defined in headers provided by the Windows SDK. This method is implemented by the writer of the debugging application. diff --git a/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptionrecord-method.md b/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptionrecord-method.md index a47017bd4281d..5801199eaa59c 100644 --- a/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptionrecord-method.md +++ b/docs/framework/unmanaged-api/debugging/iclrdatatarget3-getexceptionrecord-method.md @@ -16,7 +16,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # ICLRDataTarget3::GetExceptionRecord Method -Called by the common language runtime (CLR) data access services to retrieve the exception record associated with the target process. For example, for a dump target, this would be equivalent to the exception record passed in via the `ExceptionParam` argument to the [MiniDumpWriteDump](http://msdn.microsoft.com/library/windows/desktop/ms680360.aspx) function in the Windows Debug Help Library (DbgHelp). +Called by the common language runtime (CLR) data access services to retrieve the exception record associated with the target process. For example, for a dump target, this would be equivalent to the exception record passed in via the `ExceptionParam` argument to the [MiniDumpWriteDump](/windows/desktop/api/minidumpapiset/nf-minidumpapiset-minidumpwritedump) function in the Windows Debug Help Library (DbgHelp). ## Syntax @@ -30,13 +30,13 @@ HRESULT GetExceptionRecord( #### Parameters `bufferSize` - [in] The input buffer size, in bytes. This must be equal to `sizeof(`[MINIDUMP_EXCEPTION](http://msdn.microsoft.com/library/windows/desktop/ms680367.aspx)`)`. + [in] The input buffer size, in bytes. This must be equal to `sizeof(`[MINIDUMP_EXCEPTION](/windows/desktop/api/minidumpapiset/ns-minidumpapiset-_minidump_exception)`)`. `bufferUsed` [out] A pointer to a `ULONG32` type that receives the number of bytes actually written to the buffer. `buffer` - [out] A pointer to a memory buffer that receives a copy of the exception record. The exception record is returned as a [MINIDUMP_EXCEPTION](http://msdn.microsoft.com/library/windows/desktop/ms680367.aspx) type. + [out] A pointer to a memory buffer that receives a copy of the exception record. The exception record is returned as a [MINIDUMP_EXCEPTION](/windows/desktop/api/minidumpapiset/ns-minidumpapiset-_minidump_exception) type. ## Return Value The return value is `S_OK` on success, or a failure `HRESULT` code on failure. The `HRESULT` codes can include but are not limited to the following: @@ -48,7 +48,7 @@ HRESULT GetExceptionRecord( |`HRESULT_FROM_WIN32(ERROR_BAD_LENGTH)`|The input buffer size is not equal to `sizeof(MINIDUMP_EXCEPTION)`.| ## Remarks - [MINIDUMP_EXCEPTION](http://msdn.microsoft.com/library/windows/desktop/ms680367.aspx) is a structure defined in dbghelp.h and imagehlp.h in the Windows SDK. + [MINIDUMP_EXCEPTION](/windows/desktop/api/minidumpapiset/ns-minidumpapiset-_minidump_exception) is a structure defined in dbghelp.h and imagehlp.h in the Windows SDK. This method is implemented by the writer of the debugging application. diff --git a/docs/framework/unmanaged-api/debugging/icordebugmutabledatatarget-setthreadcontext-method.md b/docs/framework/unmanaged-api/debugging/icordebugmutabledatatarget-setthreadcontext-method.md index 8ce42b02f371e..6ecc887dc50fa 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmutabledatatarget-setthreadcontext-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmutabledatatarget-setthreadcontext-method.md @@ -27,7 +27,7 @@ HRESULT SetThreadContext( [in] A pointer to the bytes to be written. ## Remarks - The `SetThreadContext` method updates the current context for the thread specified by the operating system-defined `dwThreadID` argument. The format of the context record is determined by the platform indicated by the [ICorDebugDataTarget::GetPlatform](../../../../docs/framework/unmanaged-api/debugging/icordebugdatatarget-getplatform-method.md) method. On Windows, this is a [CONTEXT](http://msdn.microsoft.com/library/windows/desktop/ms679284.aspx) structure. + The `SetThreadContext` method updates the current context for the thread specified by the operating system-defined `dwThreadID` argument. The format of the context record is determined by the platform indicated by the [ICorDebugDataTarget::GetPlatform](../../../../docs/framework/unmanaged-api/debugging/icordebugdatatarget-getplatform-method.md) method. On Windows, this is a [CONTEXT](/windows/desktop/api/winnt/ns-winnt-_arm64_nt_context) structure. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/diagnostics/ibindingdisplay-getcurrentdisplay-method.md b/docs/framework/unmanaged-api/diagnostics/ibindingdisplay-getcurrentdisplay-method.md index 3e2ee6bb7bb60..c7d1249c391d5 100644 --- a/docs/framework/unmanaged-api/diagnostics/ibindingdisplay-getcurrentdisplay-method.md +++ b/docs/framework/unmanaged-api/diagnostics/ibindingdisplay-getcurrentdisplay-method.md @@ -36,7 +36,7 @@ HRESULT GetCurrentDisplay ( ## Remarks The [IBindingDisplay::InitializeForProcess](../../../../docs/framework/unmanaged-api/diagnostics/ibindingdisplay-initializeforprocess-method.md) method must have previously succeeded, and the program must be stopped by a debugger. - The caller must deallocate the returned `SAFEARRAY` memory by using [SafeArrayDestroy](http://msdn.microsoft.com/library/fc94f7e7-b903-4c78-905c-54df1f8d13fa). + The caller must deallocate the returned `SAFEARRAY` memory by using [SafeArrayDestroy](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-safearraydestroy). ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedencupdate-updatesymbolstore2-method.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedencupdate-updatesymbolstore2-method.md index cce8692f6c19b..51232207b62ec 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedencupdate-updatesymbolstore2-method.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedencupdate-updatesymbolstore2-method.md @@ -32,7 +32,7 @@ HRESULT UpdateSymbolStore2( #### Parameters `pIStream` - [in] A pointer to an [IStream](https://msdn.microsoft.com/library/aa380034.aspx) that contains the line information. + [in] A pointer to an [IStream](/windows/desktop/api/objidl/nn-objidl-istream) that contains the line information. `pDeltaLines` [in] A pointer to a [SYMLINEDELTA](../../../../docs/framework/unmanaged-api/diagnostics/symlinedelta-structure.md) structure that contains the lines that have changed. diff --git a/docs/framework/unmanaged-api/fusion/iassemblycacheitem-createstream-method.md b/docs/framework/unmanaged-api/fusion/iassemblycacheitem-createstream-method.md index e14cbbaad5755..2bf93efe1a806 100644 --- a/docs/framework/unmanaged-api/fusion/iassemblycacheitem-createstream-method.md +++ b/docs/framework/unmanaged-api/fusion/iassemblycacheitem-createstream-method.md @@ -48,7 +48,7 @@ HRESULT CreateStream ( [in] Format-specific flags defined in Fusion.idl. `ppIStream` - [out] A pointer to the address of the returned [IStream](https://msdn.microsoft.com/library/aa380034.aspx) instance. + [out] A pointer to the address of the returned [IStream](/windows/desktop/api/objidl/nn-objidl-istream) instance. `puliMaxSize` [in, optional] The maximum size of the stream referenced by `ppIStream`. diff --git a/docs/framework/unmanaged-api/hosting/corbindtoruntimeex-function.md b/docs/framework/unmanaged-api/hosting/corbindtoruntimeex-function.md index a7757823b6c0a..9c285ef4dca19 100644 --- a/docs/framework/unmanaged-api/hosting/corbindtoruntimeex-function.md +++ b/docs/framework/unmanaged-api/hosting/corbindtoruntimeex-function.md @@ -32,7 +32,7 @@ Enables unmanaged hosts to load the common language runtime (CLR) into a process - Control whether concurrent garbage collection or non-concurrent garbage collection is done. > [!NOTE] -> Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](http://msdn.microsoft.com/library/windows/desktop/aa384249.aspx). +> Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](/windows/desktop/WinProg64/running-32-bit-applications). - Control whether assemblies are loaded as domain-neutral. diff --git a/docs/framework/unmanaged-api/hosting/corbindtoruntimehost-function.md b/docs/framework/unmanaged-api/hosting/corbindtoruntimehost-function.md index 13eab52a861d4..b87f14d0bb5c7 100644 --- a/docs/framework/unmanaged-api/hosting/corbindtoruntimehost-function.md +++ b/docs/framework/unmanaged-api/hosting/corbindtoruntimehost-function.md @@ -53,7 +53,7 @@ HRESULT CorBindToRuntimeHost ( If `pwszBuildFlavor` is set to null, the workstation build is loaded. When running on a single-processor machine, the workstation build is always loaded, even if `pwszBuildFlavor` is set to `svr`. However, if `pwszBuildFlavor` is set to `svr` and concurrent garbage collection is specified (see the description of the `startupFlags` parameter), the server build is loaded. > [!NOTE] -> Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](http://msdn.microsoft.com/library/windows/desktop/aa384249.aspx). +> Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](/windows/desktop/WinProg64/running-32-bit-applications). `pwszHostConfigFile` [in] The name of a host configuration file that specifies the version of the CLR to load. If the file name does not include a fully qualified path, the file is assumed to be in the same directory as the executable that is making the call. diff --git a/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md b/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md index a789603be2afd..9d8a6ec2ee88d 100644 --- a/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md +++ b/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md @@ -51,7 +51,7 @@ typedef enum { |Member|Description| |------------|-----------------| -|`STARTUP_CONCURRENT_GC`|Specifies that concurrent garbage collection should be used. If the caller asks for the server build and concurrent garbage collection on a single-processor machine, the workstation build and non-concurrent garbage collection are run instead. **Note:** Concurrent garbage collection is not supported in applications that are running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](http://msdn.microsoft.com/library/windows/desktop/aa384249.aspx).| +|`STARTUP_CONCURRENT_GC`|Specifies that concurrent garbage collection should be used. If the caller asks for the server build and concurrent garbage collection on a single-processor machine, the workstation build and non-concurrent garbage collection are run instead. **Note:** Concurrent garbage collection is not supported in applications that are running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). For more information about using WOW64 on 64-bit Windows systems, see [Running 32-bit Applications](/windows/desktop/WinProg64/running-32-bit-applications).| |`STARTUP_LOADER_OPTIMIZATION_MASK`|Specifies that loader optimization shall occur.| |`STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN`|Specifies that no assemblies are loaded as domain-neutral.| |`STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN`|Specifies that all assemblies are loaded as domain-neutral.| diff --git a/docs/framework/unmanaged-api/metadata/coropenflags-enumeration.md b/docs/framework/unmanaged-api/metadata/coropenflags-enumeration.md index 37bf4d888e302..b10d6a297120d 100644 --- a/docs/framework/unmanaged-api/metadata/coropenflags-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/coropenflags-enumeration.md @@ -53,7 +53,7 @@ typedef enum CorOpenFlags |`ofCacheImage`|Obsolete. This flag is ignored.| |`ofManifestMetadata`|Obsolete. This flag is ignored.| |`ofReadOnly`|Indicates that the file should be opened for reading, and that a call to `QueryInterface` for an [IMetaDataEmit](../../../../docs/framework/unmanaged-api/metadata/imetadataemit-interface.md) cannot be made.| -|`ofTakeOwnership`|Indicates that the memory was allocated using a call to [CoTaskMemAlloc](http://msdn.microsoft.com/library/c4cb588d-9482-4f90-a92e-75b604540d5c) and will be freed by the metadata.| +|`ofTakeOwnership`|Indicates that the memory was allocated using a call to [CoTaskMemAlloc](/windows/desktop/api/combaseapi/nf-combaseapi-cotaskmemalloc) and will be freed by the metadata.| |`ofNoTypeLib`|Obsolete. This flag is ignored.| |`ofNoTransform`|Indicates that automatic transforms of .winmd files should be disabled. In other words, the projection of a Windows Runtime type to a .NET Framework type should be disabled. For more information, see [Underneath the Hood with .NET and the Windows Runtime](http://msdn.microsoft.com/magazine/jj651569.aspx).| |`ofReserved1`|Reserved for internal use.| diff --git a/docs/framework/unmanaged-api/metadata/imetadatadispenserex-openscopeonitypeinfo-method.md b/docs/framework/unmanaged-api/metadata/imetadatadispenserex-openscopeonitypeinfo-method.md index 834d9702a1e9c..0c536d173c05f 100644 --- a/docs/framework/unmanaged-api/metadata/imetadatadispenserex-openscopeonitypeinfo-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadatadispenserex-openscopeonitypeinfo-method.md @@ -34,7 +34,7 @@ HRESULT OpenScopeOnITypeInfo ( #### Parameters `pITI` - [in] Pointer to an [ITypeInfo](http://msdn.microsoft.com/library/f3356463-3373-4279-bae1-953378aa2680) interface that provides the type information on which to open the scope. + [in] Pointer to an [ITypeInfo](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/nn-oaidl-itypeinfo) interface that provides the type information on which to open the scope. `dwOpenFlags` [in] The open mode flags. diff --git a/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md b/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md index b6041ac6a90da..5ab2ac6ee9dee 100644 --- a/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md +++ b/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md @@ -168,7 +168,7 @@ pkgDebugSettings.EnableDebugging(packgeFullName, debuggerCommandLine, You’ll need to deploy this dummy debugger as part of your diagnostics tool installation, and then specify the path to this debugger in the `debuggerCommandLine` parameter. **Launching the Windows Store app** - The moment to launch the Windows Store app has finally arrived. If you’ve already already tried doing this yourself, you may have noticed that [CreateProcess](https://msdn.microsoft.com/library/windows/desktop/ms682425\(v=vs.85\).aspx) is not how you create a Windows Store app process. Instead, you’ll need to use the [IApplicationActivationManager::ActivateApplication](https://msdn.microsoft.com/library/windows/desktop/Hh706903\(v=vs.85\).aspx) method. To do that, you’ll need to get the App User Model ID of the Windows Store app that you’re launching. And that means you’ll need to do a little digging through the manifest. + The moment to launch the Windows Store app has finally arrived. If you’ve already already tried doing this yourself, you may have noticed that [CreateProcess](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa) is not how you create a Windows Store app process. Instead, you’ll need to use the [IApplicationActivationManager::ActivateApplication](/windows/desktop/api/shobjidl_core/nf-shobjidl_core-iapplicationactivationmanager-activateapplication) method. To do that, you’ll need to get the App User Model ID of the Windows Store app that you’re launching. And that means you’ll need to do a little digging through the manifest. While iterating over your packages (see "Choosing a Windows Store App to Profile" in the [Startup load](#Startup) section earlier), you’ll want to grab the set of applications contained in the current package’s manifest: @@ -236,9 +236,9 @@ pkgDebugSettings.EnableDebugging(packgeFullName, null /* debuggerCommandLine */, ### Stick to the Windows Store app APIs - As you browse the Windows API, you’ll notice that every API is documented as being applicable to desktop apps, Windows Store apps, or both. For example, the **Requirements** section of the documentation for the [InitializeCriticalSectionAndSpinCount](https://msdn.microsoft.com/library/windows/desktop/ms683476\(v=vs.85\).aspx) function indicates that the function applies to desktop apps only. In contrast, the [InitializeCriticalSectionEx](https://msdn.microsoft.com/library/windows/desktop/ms683477\(v=vs.85\).aspx) function is available for both desktop apps and Windows Store apps. + As you browse the Windows API, you’ll notice that every API is documented as being applicable to desktop apps, Windows Store apps, or both. For example, the **Requirements** section of the documentation for the [InitializeCriticalSectionAndSpinCount](/windows/desktop/api/synchapi/nf-synchapi-initializecriticalsectionandspincount) function indicates that the function applies to desktop apps only. In contrast, the [InitializeCriticalSectionEx](/windows/desktop/api/synchapi/nf-synchapi-initializecriticalsectionex) function is available for both desktop apps and Windows Store apps. - When developing your Profiler DLL, treat it as if it’s a Windows Store app and only use APIs that are documented as available to Windows Store apps. Analyze your dependencies (for example, you can run `link /dump /imports` against your Profiler DLL to audit), and then search the docs to see which of your dependencies are ok and which aren’t. In most cases, your violations can be fixed by simply replacing them with a newer form of the API that is documented as safe (for example, replacing [InitializeCriticalSectionAndSpinCount](https://msdn.microsoft.com/library/windows/desktop/ms683476\(v=vs.85\).aspx) with [InitializeCriticalSectionEx](https://msdn.microsoft.com/library/windows/desktop/ms683477\(v=vs.85\).aspx)). + When developing your Profiler DLL, treat it as if it’s a Windows Store app and only use APIs that are documented as available to Windows Store apps. Analyze your dependencies (for example, you can run `link /dump /imports` against your Profiler DLL to audit), and then search the docs to see which of your dependencies are ok and which aren’t. In most cases, your violations can be fixed by simply replacing them with a newer form of the API that is documented as safe (for example, replacing [InitializeCriticalSectionAndSpinCount](/windows/desktop/api/synchapi/nf-synchapi-initializecriticalsectionandspincount) with [InitializeCriticalSectionEx](/windows/desktop/api/synchapi/nf-synchapi-initializecriticalsectionex)). You might notice that your Profiler DLL calls some APIs that apply to desktop apps only, and yet they seem to work even when your Profiler DLL is loaded inside a Windows Store app. Be aware that it’s risky to use any API not documented for use with Windows Store apps in your Profiler DLL when loaded into a Windows Store app process: @@ -287,7 +287,7 @@ tempDir = appData.TemporaryFolder.Path; **Communicating via events** If you want simple signaling semantics between your Profiler UI and Profiler DLL, you can use events inside Windows Store apps as well as desktop apps. - From your Profiler DLL, you can simply call the [CreateEventEx](https://msdn.microsoft.com/library/windows/desktop/ms682400\(v=vs.85\).aspx) function to create a named event with any name you like. For example: + From your Profiler DLL, you can simply call the [CreateEventEx](/windows/desktop/api/synchapi/nf-synchapi-createeventexa) function to create a named event with any name you like. For example: ```cpp // Profiler DLL in Windows Store app (C++). @@ -298,7 +298,7 @@ CreateEventEx( EVENT_ALL_ACCESS); ``` - Your Profiler UI then needs to find that named event under the Windows Store app’s namespace. For example, your Profiler UI could call [CreateEventEx](https://msdn.microsoft.com/library/windows/desktop/ms682400\(v=vs.85\).aspx), specifying the event name as + Your Profiler UI then needs to find that named event under the Windows Store app’s namespace. For example, your Profiler UI could call [CreateEventEx](/windows/desktop/api/synchapi/nf-synchapi-createeventexa), specifying the event name as `AppContainerNamedObjects\\MyNamedEvent` @@ -317,7 +317,7 @@ GetAppContainerFolderPath(acSid, out acDir); ### No shutdown notifications - When running inside a Windows Store app, your Profiler DLL should not rely on either [ICorProfilerCallback::Shutdown](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-shutdown-method.md) or even [DllMain](https://msdn.microsoft.com/library/windows/desktop/ms682583\(v=vs.85\).aspx) (with `DLL_PROCESS_DETACH`) being called to notify your Profiler DLL that the Windows Store app is exiting. In fact, you should expect they will never be called. Historically, many Profiler DLLs have used those notifications as convenient places to flush caches to disk, close files, send notifications back to the Profiler UI, etc. But now your Profiler DLL needs to be organized a little differently. + When running inside a Windows Store app, your Profiler DLL should not rely on either [ICorProfilerCallback::Shutdown](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-shutdown-method.md) or even [DllMain](/windows/desktop/Dlls/dllmain) (with `DLL_PROCESS_DETACH`) being called to notify your Profiler DLL that the Windows Store app is exiting. In fact, you should expect they will never be called. Historically, many Profiler DLLs have used those notifications as convenient places to flush caches to disk, close files, send notifications back to the Profiler UI, etc. But now your Profiler DLL needs to be organized a little differently. Your Profiler DLL should be logging information as it goes. For performance reasons, you may want to batch information in memory and flush it to disk as the batch grows in size past some threshold. But assume that any information not yet flushed to disk can be lost. This means you’ll want to pick your threshold wisely, and that your Profiler UI needs to be hardened to deal with incomplete information written by the Profiler DLL. diff --git a/docs/framework/unmanaged-api/profiling/profiling-overview.md b/docs/framework/unmanaged-api/profiling/profiling-overview.md index fa4ea7789215d..d3716abb0a6ea 100644 --- a/docs/framework/unmanaged-api/profiling/profiling-overview.md +++ b/docs/framework/unmanaged-api/profiling/profiling-overview.md @@ -192,7 +192,7 @@ Profiling architecture ## Using COM - Although the profiling interfaces are defined as COM interfaces, the common language runtime (CLR) does not actually initialize COM to use these interfaces. The reason is to avoid having to set the threading model by using the [CoInitialize](http://msdn.microsoft.com/library/windows/desktop/ms678543\(v=vs.85\).aspx) function before the managed application has had a chance to specify its desired threading model. Similarly, the profiler itself should not call `CoInitialize`, because it may pick a threading model that is incompatible with the application being profiled and may cause the application to fail. + Although the profiling interfaces are defined as COM interfaces, the common language runtime (CLR) does not actually initialize COM to use these interfaces. The reason is to avoid having to set the threading model by using the [CoInitialize](/windows/desktop/api/objbase/nf-objbase-coinitialize) function before the managed application has had a chance to specify its desired threading model. Similarly, the profiler itself should not call `CoInitialize`, because it may pick a threading model that is incompatible with the application being profiled and may cause the application to fail. [Back to top](#top) diff --git a/docs/framework/unmanaged-api/tlbexp/gettypelibinfo-function.md b/docs/framework/unmanaged-api/tlbexp/gettypelibinfo-function.md index 18394fe0bde74..96950e1b90b21 100644 --- a/docs/framework/unmanaged-api/tlbexp/gettypelibinfo-function.md +++ b/docs/framework/unmanaged-api/tlbexp/gettypelibinfo-function.md @@ -18,7 +18,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # GetTypeLibInfo Function -Returns information about the specified type library by examining its [TLIBATTR](https://msdn.microsoft.com/library/ms221376\(v=vs.85\).aspx) structure. +Returns information about the specified type library by examining its [TLIBATTR](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/ns-oaidl-tagtlibattr) structure. ## Syntax @@ -44,7 +44,7 @@ HRESULT GetTypeLibInfo( [out] The localization ID of the type library. `pTypeLibPlatform` - [out] A [SYSKIND](https://msdn.microsoft.com/library/ms221272\(v=vs.85\).aspx) flag that identifies the target operating system for the type library. Common values are SYS_WIN32 and SYS_WIN64. + [out] A [SYSKIND](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/ne-oaidl-tagsyskind) flag that identifies the target operating system for the type library. Common values are SYS_WIN32 and SYS_WIN64. `pTypeLibMajorVer` [out] The major version number of the type library. For example, for version *x.y*, the major version number is *x*. @@ -68,4 +68,4 @@ HRESULT GetTypeLibInfo( ## See Also [Tlbexp Helper Functions](../../../../docs/framework/unmanaged-api/tlbexp/index.md) - [LoadTypeLibEx Function](https://msdn.microsoft.com/library/ms221249\(v=vs.85\).aspx) + [LoadTypeLibEx Function](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-loadtypelibex) diff --git a/docs/framework/unmanaged-api/tlbexp/itypelibresolver-interface.md b/docs/framework/unmanaged-api/tlbexp/itypelibresolver-interface.md index 0a9fd5fc5bd8b..64fdb19396dfe 100644 --- a/docs/framework/unmanaged-api/tlbexp/itypelibresolver-interface.md +++ b/docs/framework/unmanaged-api/tlbexp/itypelibresolver-interface.md @@ -37,4 +37,4 @@ Provides the [ResolveTypeLib method](../../../../docs/framework/unmanaged-api/tl ## See Also [Tlbexp Helper Functions](../../../../docs/framework/unmanaged-api/tlbexp/index.md) - [LoadTypeLibEx function](https://msdn.microsoft.com/library/windows/desktop/ms221249\(v=vs.85\).aspx) + [LoadTypeLibEx function](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-loadtypelibex) diff --git a/docs/framework/unmanaged-api/tlbexp/loadtypelibwithresolver-function.md b/docs/framework/unmanaged-api/tlbexp/loadtypelibwithresolver-function.md index 4caacfb8eab16..35c050583d981 100644 --- a/docs/framework/unmanaged-api/tlbexp/loadtypelibwithresolver-function.md +++ b/docs/framework/unmanaged-api/tlbexp/loadtypelibwithresolver-function.md @@ -35,7 +35,7 @@ HRESULT LoadTypeLibWithResolver( [in] The file path of the type library. `regkind` - [in] A [REGKIND enumeration](https://msdn.microsoft.com/library/windows/desktop/ms221159.aspx) flag that controls how the type library is registered. Its possible values are: + [in] A [REGKIND enumeration](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/ne-oleauto-tagregkind) flag that controls how the type library is registered. Its possible values are: - `REGKIND_DEFAULT`: Use default registration behavior. @@ -89,4 +89,4 @@ HRESULT LoadTypeLibWithResolver( ## See Also [Tlbexp Helper Functions](../../../../docs/framework/unmanaged-api/tlbexp/index.md) - [LoadTypeLibEx Function](https://msdn.microsoft.com/library/windows/desktop/ms221249\(v=vs.85\).aspx) + [LoadTypeLibEx Function](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-loadtypelibex) diff --git a/docs/framework/unmanaged-api/tlbexp/resolvetypelib-method.md b/docs/framework/unmanaged-api/tlbexp/resolvetypelib-method.md index 49d0852c94ad7..eb1f4ba999e02 100644 --- a/docs/framework/unmanaged-api/tlbexp/resolvetypelib-method.md +++ b/docs/framework/unmanaged-api/tlbexp/resolvetypelib-method.md @@ -34,7 +34,7 @@ HRESULT ResolveTypeLib( #### Parameters `bstrSimpleName` - [in] A [BSTR](http://msdn.microsoft.com/library/1b2d7d2c-47af-4389-a6b6-b01b7e915228) that contains the simple name of the type library. + [in] A [BSTR](https://docs.microsoft.com/previous-versions/windows/desktop/automat/bstr) that contains the simple name of the type library. `tlbid` [in] The GUID assigned to the type library in the registry. @@ -49,15 +49,15 @@ HRESULT ResolveTypeLib( [in] The minor version number of the type library. For example, for version *x.y*, the minor version number is *y*. `syskind` - [in] A [SYSKIND](http://msdn.microsoft.com/library/662048b2-59a8-48ca-9e4f-2f9a5306faa1) flag that identifies the operating environment. Common values are SYS_WIN32 and SYS_WIN64. + [in] A [SYSKIND](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/ne-oaidl-tagsyskind) flag that identifies the operating environment. Common values are SYS_WIN32 and SYS_WIN64. `pbstrResolvedTlbName` - [out] A pointer to a [BSTR](http://msdn.microsoft.com/library/1b2d7d2c-47af-4389-a6b6-b01b7e915228) that contains the full path of the type library named in the `bstrSimpleName` parameter. + [out] A pointer to a [BSTR](https://docs.microsoft.com/previous-versions/windows/desktop/automat/bstr) that contains the full path of the type library named in the `bstrSimpleName` parameter. ## Remarks The `ResolveTypeLib` method is called by the [LoadTypeLibWithResolver function](../../../../docs/framework/unmanaged-api/tlbexp/loadtypelibwithresolver-function.md) during [Tlbexp.exe (Type Library Exporter)](../../../../docs/framework/tools/tlbexp-exe-type-library-exporter.md) processing. - Custom implementations of this interface must return a [BSTR](http://msdn.microsoft.com/library/1b2d7d2c-47af-4389-a6b6-b01b7e915228) that contains the full path of the type library named in the `bstrSimpleName` parameter. + Custom implementations of this interface must return a [BSTR](https://docs.microsoft.com/previous-versions/windows/desktop/automat/bstr) that contains the full path of the type library named in the `bstrSimpleName` parameter. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). @@ -70,4 +70,4 @@ HRESULT ResolveTypeLib( ## See Also [Tlbexp Helper Functions](../../../../docs/framework/unmanaged-api/tlbexp/index.md) - [LoadTypeLibEx](http://msdn.microsoft.com/library/56a7f9e1-810b-4a42-aa4d-691f4304f5ef) + [LoadTypeLibEx](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-loadtypelibex) diff --git a/docs/framework/unmanaged-api/wmi/beginenumeration.md b/docs/framework/unmanaged-api/wmi/beginenumeration.md index 1bf5909a724a7..5493b8ffd349f 100644 --- a/docs/framework/unmanaged-api/wmi/beginenumeration.md +++ b/docs/framework/unmanaged-api/wmi/beginenumeration.md @@ -38,7 +38,7 @@ HRESULT BeginEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lEnumFlags` [in] A bitwise combination of the flags or values described in the [Remarks](#remarks) section that controls the properties included in the enumeration. @@ -56,7 +56,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::BeginEnumeration](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) method. +This function wraps a call to the [IWbemClassObject::BeginEnumeration](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) method. The flags that can be passed as the `lEnumFlags` argument are defined in the *WbemCli.h* header file, or you can define them as constants in your code. You can combine one flag from each group with any flag from any other group. However, flags from the same group are mutually exclusive. diff --git a/docs/framework/unmanaged-api/wmi/beginmethodenumeration.md b/docs/framework/unmanaged-api/wmi/beginmethodenumeration.md index 6f2067dd3963f..2da37298eaebf 100644 --- a/docs/framework/unmanaged-api/wmi/beginmethodenumeration.md +++ b/docs/framework/unmanaged-api/wmi/beginmethodenumeration.md @@ -38,7 +38,7 @@ HRESULT BeginMethodEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lEnumFlags` [in] Zero (0) for all methods, or a flag that specifies the scope of the enumeration. The following flags are defined in the *WbemCli.h* header file, or you can define them as constants in your code: @@ -59,9 +59,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::BeginMethodEnumeration](https://msdn.microsoft.com/library/aa391435(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::BeginMethodEnumeration](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-beginmethodenumeration) method. -This method call is only supported if the current object is a class definition. Method manipulation is not available from [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) pointers that point to instances. The order in which methods are enumerated is guaranteed to be invariant for a given instance of [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx). +This method call is only supported if the current object is a class definition. Method manipulation is not available from [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) pointers that point to instances. The order in which methods are enumerated is guaranteed to be invariant for a given instance of [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject). ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/blessiwbemservices.md b/docs/framework/unmanaged-api/wmi/blessiwbemservices.md index 7b2f57feec253..a389814adfbff 100644 --- a/docs/framework/unmanaged-api/wmi/blessiwbemservices.md +++ b/docs/framework/unmanaged-api/wmi/blessiwbemservices.md @@ -18,7 +18,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # BlessIWbemServices function -Indicates whether the user credentials permit access to the specified [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) class. +Indicates whether the user credentials permit access to the specified [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) class. [!INCLUDE[internalonly-unmanaged](../../../../includes/internalonly-unmanaged.md)] @@ -38,7 +38,7 @@ HRESULT BlessIWbemServices ( ## Parameters `pIWbemServices` -[in] A pointer to the [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object for which permissions are required. +[in] A pointer to the [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object for which permissions are required. `strUser` [in] The user name. diff --git a/docs/framework/unmanaged-api/wmi/blessiwbemservicesobject.md b/docs/framework/unmanaged-api/wmi/blessiwbemservicesobject.md index 07c4d798323ff..cfada586f306b 100644 --- a/docs/framework/unmanaged-api/wmi/blessiwbemservicesobject.md +++ b/docs/framework/unmanaged-api/wmi/blessiwbemservicesobject.md @@ -18,7 +18,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # BlessIWbemServicesObject function -Indicates whether the user credentials permit access to a specified [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object. +Indicates whether the user credentials permit access to a specified [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object. [!INCLUDE[internalonly-unmanaged](../../../../includes/internalonly-unmanaged.md)] diff --git a/docs/framework/unmanaged-api/wmi/clone.md b/docs/framework/unmanaged-api/wmi/clone.md index 97d2296d6e92c..93b6f8cee77b3 100644 --- a/docs/framework/unmanaged-api/wmi/clone.md +++ b/docs/framework/unmanaged-api/wmi/clone.md @@ -38,7 +38,7 @@ HRESULT Clone ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `ppCopy` [out] A new object that is a complete lone of `ptr`. This argument cannot be `null` if it receives the copy of the current object. @@ -56,7 +56,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::Clone](https://msdn.microsoft.com/library/aa391436(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::Clone](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-clone) method. The cloned object is a COM object that has a reference count of 1. diff --git a/docs/framework/unmanaged-api/wmi/cloneenumwbemclassobject.md b/docs/framework/unmanaged-api/wmi/cloneenumwbemclassobject.md index 471ded967b50e..59e0537153d3d 100644 --- a/docs/framework/unmanaged-api/wmi/cloneenumwbemclassobject.md +++ b/docs/framework/unmanaged-api/wmi/cloneenumwbemclassobject.md @@ -39,7 +39,7 @@ HRESULT CloneEnumWbemClassObject ( ## Parameters `ppEnum` -[out] Receives a pointer to a new [IEnumWbemClassObject](https://msdn.microsoft.com/library/aa390857(v=vs.85).aspx). +[out] Receives a pointer to a new [IEnumWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-ienumwbemclassobject). `authLevel` [in] The authorization level. @@ -48,7 +48,7 @@ HRESULT CloneEnumWbemClassObject ( [in] The impersonation level. `pCurrentEnumWbemClassObject` -[out] A pointer to the [IEnumWbemClassObject](https://msdn.microsoft.com/library/aa390857(v=vs.85).aspx) instance to be cloned. +[out] A pointer to the [IEnumWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-ienumwbemclassobject) instance to be cloned. `strUser` [in] The user name. See the [ConnectServerWmi](connectserverwmi.md) function for more information. @@ -73,7 +73,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IEnumWbemClassObject::Clone](https://msdn.microsoft.com/library/aa390859(v=vs.85).aspx) method. +This function wraps a call to the [IEnumWbemClassObject::Clone](/windows/desktop/api/wbemcli/nf-wbemcli-ienumwbemclassobject-clone) method. This method makes only a "best effort" copy. Due to the dynamic nature of many CIM objects, it is possible that the new enumerator does not enumerate the same set of objects as the source enumerator. @@ -81,7 +81,7 @@ If the function call fails, you can obtain additional error information by calli ## Example -For an example, see the [IEnumWbemClassObject::Clone](https://msdn.microsoft.com/library/aa390859(v=vs.85).aspx) method. +For an example, see the [IEnumWbemClassObject::Clone](/windows/desktop/api/wbemcli/nf-wbemcli-ienumwbemclassobject-clone) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/compareto.md b/docs/framework/unmanaged-api/wmi/compareto.md index f910a3a00357a..d0b5e249cea9c 100644 --- a/docs/framework/unmanaged-api/wmi/compareto.md +++ b/docs/framework/unmanaged-api/wmi/compareto.md @@ -39,14 +39,14 @@ HRESULT CompareTo ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `flags` [in] A bitwise combination of the flags that specify the object characteristics to consider for the comparison. See the [Remarks](#remarks) section for more information. `pCompareTo` -[in] The object for comparison. `pcompareTo` must be a valid [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance; it cannot be `null`. +[in] The object for comparison. `pcompareTo` must be a valid [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance; it cannot be `null`. ## Return value @@ -63,7 +63,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::CompareTo](https://msdn.microsoft.com/library/aa391437(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::CompareTo](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-compareto) method. The flags that can be passed as the `lEnumFlags` argument are defined in the *WbemCli.h* header file, or you can define them as constants in your code. You can specify the individual characteristics involved in the comparison by specifying a bitwise combination of the following flags: diff --git a/docs/framework/unmanaged-api/wmi/connectserverwmi.md b/docs/framework/unmanaged-api/wmi/connectserverwmi.md index 22623bea534e7..f3c42c51cabae 100644 --- a/docs/framework/unmanaged-api/wmi/connectserverwmi.md +++ b/docs/framework/unmanaged-api/wmi/connectserverwmi.md @@ -70,10 +70,10 @@ HRESULT ConnectServerWmi ( | NTLMDOMAIN:*domain name* | NT LAN Manager authentication is used, and this parameter contains an NTLM domain name. | `pCtx` -[in] Typically, this parameter is is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465%28v=vs.85%29.aspx) object required by one or more dynamic class providers. +[in] Typically, this parameter is is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) object required by one or more dynamic class providers. `ppNamespace` -[out] When the function returns, receives a pointer to an [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object bound to the specified namespace. It is set to point to `null` when there is an error. +[out] When the function returns, receives a pointer to an [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object bound to the specified namespace. It is set to point to `null` when there is an error. `impLevel` [in] The impersonation level. diff --git a/docs/framework/unmanaged-api/wmi/createclassenumwmi.md b/docs/framework/unmanaged-api/wmi/createclassenumwmi.md index ebe30d3db6a8e..5cf45ade2c259 100644 --- a/docs/framework/unmanaged-api/wmi/createclassenumwmi.md +++ b/docs/framework/unmanaged-api/wmi/createclassenumwmi.md @@ -59,7 +59,7 @@ HRESULT CreateClassEnumWmi ( The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ONLY` for best performance. `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that can be used by the provider that is providing the requested classes. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that can be used by the provider that is providing the requested classes. `ppEnum` [out] Receives the pointer to the enumerator. @@ -71,7 +71,7 @@ The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ [in] The impersonation level. `pCurrentNamespace` -[in] A pointer to an [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object that represents the current namespace. +[in] A pointer to an [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object that represents the current namespace. `strUser` [in] The user name. See the [ConnectServerWmi](connectserverwmi.md) function for more information. @@ -99,7 +99,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::CreateClassEnum](https://msdn.microsoft.com/library/aa392095(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::CreateClassEnum](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-createclassenum) method. If the function call fails, you can obtain additional error information by calling the [GetErrorInfo](geterrorinfo.md) function. diff --git a/docs/framework/unmanaged-api/wmi/createinstanceenumwmi.md b/docs/framework/unmanaged-api/wmi/createinstanceenumwmi.md index 027b6bb2ddb74..59cce0e941ba1 100644 --- a/docs/framework/unmanaged-api/wmi/createinstanceenumwmi.md +++ b/docs/framework/unmanaged-api/wmi/createinstanceenumwmi.md @@ -59,7 +59,7 @@ HRESULT CreateInstanceEnumWmi ( The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ONLY` for best performance. `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that may be used by the provider that is providing the requested instances. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that may be used by the provider that is providing the requested instances. `ppEnum` [out] Receives the pointer to the enumerator. @@ -71,7 +71,7 @@ The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ [in] The impersonation level. `pCurrentNamespace` -[in] A pointer to an [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object that represents the current namespace. +[in] A pointer to an [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object that represents the current namespace. `strUser` [in] The user name. See the [ConnectServerWmi](connectserverwmi.md) function for more information. @@ -99,7 +99,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::CreateClassEnum](https://msdn.microsoft.com/library/aa392097(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::CreateClassEnum](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-createinstanceenum) method. Note that the returned enumerator can have zero elements. diff --git a/docs/framework/unmanaged-api/wmi/delete.md b/docs/framework/unmanaged-api/wmi/delete.md index f4767dbf85004..b9f8e98e26f38 100644 --- a/docs/framework/unmanaged-api/wmi/delete.md +++ b/docs/framework/unmanaged-api/wmi/delete.md @@ -38,7 +38,7 @@ HRESULT Delete ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The name of the property to delete. `wszName` must be a pointer to a valid `LPCWSTR`. @@ -61,7 +61,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::Delete](https://msdn.microsoft.com/library/aa391438(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::Delete](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-delete) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/deletemethod.md b/docs/framework/unmanaged-api/wmi/deletemethod.md index 2e0fc93a1a3db..ea0dc400ced70 100644 --- a/docs/framework/unmanaged-api/wmi/deletemethod.md +++ b/docs/framework/unmanaged-api/wmi/deletemethod.md @@ -38,7 +38,7 @@ HRESULT Delete ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The name of the method to remove from the class table. `wszName` must be a pointer to a valid `LPCWSTR`. @@ -55,9 +55,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::DeleteMethod](https://msdn.microsoft.com/library/aa391439(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::DeleteMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-deletemethod) method. -Method deletion is not supported for [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) pointers that point to CIM instances. +Method deletion is not supported for [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) pointers that point to CIM instances. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/endenumeration.md b/docs/framework/unmanaged-api/wmi/endenumeration.md index 14672dab3c5f7..aa78b77af40f5 100644 --- a/docs/framework/unmanaged-api/wmi/endenumeration.md +++ b/docs/framework/unmanaged-api/wmi/endenumeration.md @@ -37,7 +37,7 @@ HRESULT EndEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. ## Return value @@ -51,7 +51,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::EndEnumeration](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) method. +This function wraps a call to the [IWbemClassObject::EndEnumeration](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) method. A call to the `EndEnumeration` function is not required, but it is recommended because it releases resources associated with the enumeration. However, the resoruces are deallocated automatically when the next enumeration is started or the object is released. diff --git a/docs/framework/unmanaged-api/wmi/endmethodenumeration.md b/docs/framework/unmanaged-api/wmi/endmethodenumeration.md index e4455812ac58a..ad5828eaa82f2 100644 --- a/docs/framework/unmanaged-api/wmi/endmethodenumeration.md +++ b/docs/framework/unmanaged-api/wmi/endmethodenumeration.md @@ -37,7 +37,7 @@ HRESULT EndMethodEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. ## Return value @@ -50,7 +50,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::EndMethodEnumeration](https://msdn.microsoft.com/library/aa391441(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::EndMethodEnumeration](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-endmethodenumeration) method. The caller begins the enumeration sequence using [BeginMethodEnumeration function](beginmethodenumeration.md), and then calls the [NextMethod function](nextmethod.md )until the method returns `WBEM_S_NO_MORE_DATA`. The caller optionally finishes the sequence by calling `EndMethodEnumeration`. The caller may terminate the enumeration early by calling `EndMethodEnumeration` at any time. diff --git a/docs/framework/unmanaged-api/wmi/execnotificationquerywmi.md b/docs/framework/unmanaged-api/wmi/execnotificationquerywmi.md index 7c588ea9a88dd..1bb9408360e74 100644 --- a/docs/framework/unmanaged-api/wmi/execnotificationquerywmi.md +++ b/docs/framework/unmanaged-api/wmi/execnotificationquerywmi.md @@ -57,7 +57,7 @@ HRESULT ExecNotificationQueryWmi ( | `WBEM_FLAG_FORWARD_ONLY` | 0x20 | The function returns a forward-only enumerator. Typically, forward-only enumerators are faster and use less memory than conventional enumerators, but they do not allow calls to [Clone](clone.md). | `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that can be used by the provider that is providing the requested events. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that can be used by the provider that is providing the requested events. `ppEnum` [out] If no error occurs, receives the pointer to the enumerator that allows the caller to retrieve the instances in the query's result set. See the [Remarks](#remarks) section for more information. @@ -69,7 +69,7 @@ HRESULT ExecNotificationQueryWmi ( [in] The impersonation level. `pCurrentNamespace` -[in] A pointer to an [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object that represents the current namespace. +[in] A pointer to an [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object that represents the current namespace. `strUser` [in] The user name. See the [ConnectServerWmi](connectserverwmi.md) function for more information. @@ -103,7 +103,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::ExecNotificationQuery](https://msdn.microsoft.com/library/aa392105(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::ExecNotificationQuery](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-execnotificationquery) method. After the function returns, the caller periodically passes the returned `ppEnum` object to the [Next](next.md) function to see if any events are available. diff --git a/docs/framework/unmanaged-api/wmi/execquerywmi.md b/docs/framework/unmanaged-api/wmi/execquerywmi.md index 113847c92dc4c..fad84904246e9 100644 --- a/docs/framework/unmanaged-api/wmi/execquerywmi.md +++ b/docs/framework/unmanaged-api/wmi/execquerywmi.md @@ -64,7 +64,7 @@ HRESULT ExecQueryWmi ( The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ONLY` for best performance. `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that can be used by the provider that is providing the requested classes. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that can be used by the provider that is providing the requested classes. `ppEnum` [out] If no error occurs, receives the pointer to the enumerator that allows the caller to retrieve the instances in the query's result set. The query can have a result set with zero instances. See the [Remarks](#remarks) section for more information. @@ -76,7 +76,7 @@ The recommended flags are `WBEM_FLAG_RETURN_IMMEDIATELY` and `WBEM_FLAG_FORWARD_ [in] The impersonation level. `pCurrentNamespace` -[in] A pointer to an [IWbemServices](https://msdn.microsoft.com/library/aa392093(v=vs.85).aspx) object that represents the current namespace. +[in] A pointer to an [IWbemServices](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemservices) object that represents the current namespace. `strUser` [in] The user name. See the [ConnectServerWmi](connectserverwmi.md) function for more information. @@ -107,9 +107,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::ExecQuery](https://msdn.microsoft.com/library/aa392107(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::ExecQuery](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-execquery) method. -This function processes the query specified in the `strQuery` parameter and creates an enumerator through which the caller can access the query results. The enumerator is a pointer to an [IEnumWbemClassObject](https://msdn.microsoft.com/library/aa390857(v=vs.85).aspx) interface; the query results are instances of class objects made available through the [IWbemClassObject](https://msdn.microsoft.com/library/aa391433(v=vs.85).aspx) interface. +This function processes the query specified in the `strQuery` parameter and creates an enumerator through which the caller can access the query results. The enumerator is a pointer to an [IEnumWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-ienumwbemclassobject) interface; the query results are instances of class objects made available through the [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) interface. There are limits to the number of `AND` and `OR` keywords that can be used in WQL queries. Large numbers of WQL keywords used in a complex query can cause WMI to return the `WBEM_E_QUOTA_VIOLATION` (or 0x8004106c) error code as an `HRESULT` value. The limit of WQL keywords depends on how complex the query is. diff --git a/docs/framework/unmanaged-api/wmi/formatfromrawvalue.md b/docs/framework/unmanaged-api/wmi/formatfromrawvalue.md index e3ad1ec37292e..7547fb58ad916 100644 --- a/docs/framework/unmanaged-api/wmi/formatfromrawvalue.md +++ b/docs/framework/unmanaged-api/wmi/formatfromrawvalue.md @@ -38,7 +38,7 @@ int FormatFromRawValue ( ## Parameters `dwCounterType` -[in] The counter type. For a list of counter types, see [WMI Performance Counter Types](https://msdn.microsoft.com/library/aa394569(v=vs.85).aspx). `dwCounterType` can be any counter type except for `PERF_LARGE_RAW_FRACTION` and `PERF_LARGE_RAW_BASE`. +[in] The counter type. For a list of counter types, see [WMI Performance Counter Types](/windows/desktop/WmiSdk/wmi-performance-counter-types). `dwCounterType` can be any counter type except for `PERF_LARGE_RAW_FRACTION` and `PERF_LARGE_RAW_BASE`. `dwFormat` [in] The format to which to convert the raw performance data. It can be one of the following values: diff --git a/docs/framework/unmanaged-api/wmi/get.md b/docs/framework/unmanaged-api/wmi/get.md index 4b3da0428d670..fb2f569a2b529 100644 --- a/docs/framework/unmanaged-api/wmi/get.md +++ b/docs/framework/unmanaged-api/wmi/get.md @@ -42,7 +42,7 @@ HRESULT Get ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The name of the property. @@ -54,7 +54,7 @@ HRESULT Get ( [out] If the function returns successfully, contains the value of the `wszName` property. The `pval` argument is assigned the correct type and value for the qualifier. `pvtType` -[out] If the function returns successfully, contains a [CIM-type constant](https://msdn.microsoft.com/library/aa386309(v=vs.85).aspx) that indicates the property type. Its value can also be `null`. +[out] If the function returns successfully, contains a [CIM-type constant](/windows/desktop/api/wbemcli/ne-wbemcli-tag_cimtype_enumeration) that indicates the property type. Its value can also be `null`. `plFlavor` [out] If the function returns successfully, receives information about the origin of the property. Its value can be `null`, or one of the following WBEM_FLAVOR_TYPE constants defined in the *WbemCli.h* header file: @@ -79,11 +79,11 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::Get](https://msdn.microsoft.com/library/aa391442(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::Get](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-get) method. The `Get` function can also return system properties. -The `pVal` argument is assigned the correct type and value for the qualifier and the COM [VariantInit](https://msdn.microsoft.com/library/ms221402(v=vs.85).aspx) function +The `pVal` argument is assigned the correct type and value for the qualifier and the COM [VariantInit](https://docs.microsoft.com/previous-versions/windows/desktop/api/oleauto/nf-oleauto-variantinit) function ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getcurrentapartmenttype.md b/docs/framework/unmanaged-api/wmi/getcurrentapartmenttype.md index 63522299a4e38..3e309b8d5d3da 100644 --- a/docs/framework/unmanaged-api/wmi/getcurrentapartmenttype.md +++ b/docs/framework/unmanaged-api/wmi/getcurrentapartmenttype.md @@ -38,10 +38,10 @@ HRESULT GetCurrentApartmentType ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IComThreadingInfo](https://msdn.microsoft.com/library/windows/desktop/ms694502(v=vs.85).aspx) instance. +[in] A pointer to an [IComThreadingInfo](/windows/desktop/api/objidlbase/nn-objidlbase-icomthreadinginfo) instance. `aptType` -[out] A pointer to an [APTTYPE](https://msdn.microsoft.com/library/windows/desktop/ms693793(v=vs.85).aspx) enumeration value that indicates the caller's apartment. +[out] A pointer to an [APTTYPE](/windows/desktop/api/objidlbase/ne-objidlbase-_apttype) enumeration value that indicates the caller's apartment. ## Return value @@ -53,7 +53,7 @@ HRESULT GetCurrentApartmentType ( ## Remarks -This function wraps a call to the [IComThreadingInfo::GetCurrentApartmentType](https://msdn.microsoft.com/library/windows/desktop/ms683752(v=vs.85).aspx) method. +This function wraps a call to the [IComThreadingInfo::GetCurrentApartmentType](/windows/desktop/api/objidlbase/nf-objidlbase-icomthreadinginfo-getcurrentapartmenttype) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getdemultiplexedstub.md b/docs/framework/unmanaged-api/wmi/getdemultiplexedstub.md index c64c99373ec5c..4cf453260b3ef 100644 --- a/docs/framework/unmanaged-api/wmi/getdemultiplexedstub.md +++ b/docs/framework/unmanaged-api/wmi/getdemultiplexedstub.md @@ -35,7 +35,7 @@ HRESULT GetDemultiplexedStub ( ## Parameters `pObject` -[in] A pointer to the client's in-process implementation of [IWbemObjectSink](https://msdn.microsoft.com/library/aa391787(v=vs.85).aspx). +[in] A pointer to the client's in-process implementation of [IWbemObjectSink](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemobjectsink). `isLocal` [in] A flag that indicates whether the event is local (`true`); otherwise, `false`. diff --git a/docs/framework/unmanaged-api/wmi/geterrorinfo.md b/docs/framework/unmanaged-api/wmi/geterrorinfo.md index 26d9383f6efee..5e1d11dd2a8a3 100644 --- a/docs/framework/unmanaged-api/wmi/geterrorinfo.md +++ b/docs/framework/unmanaged-api/wmi/geterrorinfo.md @@ -30,11 +30,11 @@ IErrorInfo* GetErrorInfo(); ## Return value -An pointer to an [IErrorInfo](https://msdn.microsoft.com/library/windows/desktop/ms221233(v=vs.85).aspx) object if the function call succeeds, or `null` if it fails. +An pointer to an [IErrorInfo](https://docs.microsoft.com/previous-versions/windows/desktop/api/oaidl/nn-oaidl-ierrorinfo) object if the function call succeeds, or `null` if it fails. ## Remarks -This function wraps a call to the [IComThreadingInfo::GetErrorInfo](https://msdn.microsoft.com/library/windows/desktop/ms683752(v=vs.85).aspx) method. +This function wraps a call to the [IComThreadingInfo::GetErrorInfo](/windows/desktop/api/objidlbase/nf-objidlbase-icomthreadinginfo-getcurrentapartmenttype) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getmethod.md b/docs/framework/unmanaged-api/wmi/getmethod.md index 28a4c79198d93..22ffa5bc054bd 100644 --- a/docs/framework/unmanaged-api/wmi/getmethod.md +++ b/docs/framework/unmanaged-api/wmi/getmethod.md @@ -41,7 +41,7 @@ HRESULT GetMethod ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The method name. This parameter cannot be `null` and must point to a valid `LPCWSTR`. @@ -50,10 +50,10 @@ HRESULT GetMethod ( [in] Reserved. This parameter must be 0. `ppInSignature` -[out] A pointer to the address of an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance that describes the in paramteers to the method. This parameter is ignored if it is set to `null`. +[out] A pointer to the address of an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance that describes the in paramteers to the method. This parameter is ignored if it is set to `null`. `ppOutSignature` -[out] A pointer to the address of an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance that describes the out parameters to the method. This parameter is ignored if it is set to `null`. +[out] A pointer to the address of an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance that describes the out parameters to the method. This parameter is ignored if it is set to `null`. ## Return value @@ -67,11 +67,11 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetMethod](https://msdn.microsoft.com/library/aa391443(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getmethod) method. -Windows Management can set the [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) pointer to `null` if the method has no in parameters. +Windows Management can set the [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) pointer to `null` if the method has no in parameters. -In `ppInSignature` and `ppOutSignature` describe in and out parameters, respectively, as properties in a `IWbemClassObject` instance of the system class [_Parameters](https://msdn.microsoft.com/library/aa394667(v=vs.85).aspx). The properties in `ppInsignature` are named **Param***n*, where *n* is the position of the parameter in the method signature (such as `Param1`, `Param2`, etc.). The properties in `ppOutSignature` are also named **Param***n*, and the return value is named **ReturnValue**. For more information and an example, see [IWbemClassObject::GetMethod method](https://msdn.microsoft.com/library/aa391443(v=vs.85).aspx). +In `ppInSignature` and `ppOutSignature` describe in and out parameters, respectively, as properties in a `IWbemClassObject` instance of the system class [_Parameters](/windows/desktop/WmiSdk/--parameters). The properties in `ppInsignature` are named **Param***n*, where *n* is the position of the parameter in the method signature (such as `Param1`, `Param2`, etc.). The properties in `ppOutSignature` are also named **Param***n*, and the return value is named **ReturnValue**. For more information and an example, see [IWbemClassObject::GetMethod method](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getmethod). ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getmethodorigin.md b/docs/framework/unmanaged-api/wmi/getmethodorigin.md index 6352b3d41cb83..676c7d396c6fe 100644 --- a/docs/framework/unmanaged-api/wmi/getmethodorigin.md +++ b/docs/framework/unmanaged-api/wmi/getmethodorigin.md @@ -39,7 +39,7 @@ HRESULT GetMethodOrigin ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszMethodName` [in] The name of the method for the object whose owning class is being requested. @@ -59,7 +59,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetMethodOrigin](https://msdn.microsoft.com/library/aa391443(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetMethodOrigin](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getmethod) method. Because a class can inherit methods from one or more base classes, developers often want to determine the class in which a given method is defined. diff --git a/docs/framework/unmanaged-api/wmi/getmethodqualifierset.md b/docs/framework/unmanaged-api/wmi/getmethodqualifierset.md index 2a00335ce8181..5bd998f95065c 100644 --- a/docs/framework/unmanaged-api/wmi/getmethodqualifierset.md +++ b/docs/framework/unmanaged-api/wmi/getmethodqualifierset.md @@ -39,7 +39,7 @@ HRESULT GetMethodQualifierSet ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszMethod` [in] The method name. `wszMethod` must point to a valid `LPCWSTR`. @@ -59,11 +59,11 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetMethodQualifierSet](https://msdn.microsoft.com/library/aa391446(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetMethodQualifierSet](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getmethodqualifierset) method. -A call to this function is supported only if the current object is a CIM class definition. Method manipulation is not available for [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) ponters that point to CIM instances. +A call to this function is supported only if the current object is a CIM class definition. Method manipulation is not available for [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) ponters that point to CIM instances. -Because each method may have its own qualifiers, the [IWbemQualifierSet pointer](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) lets the caller add, edit, or delete these qualifiers. +Because each method may have its own qualifiers, the [IWbemQualifierSet pointer](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) lets the caller add, edit, or delete these qualifiers. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getnames.md b/docs/framework/unmanaged-api/wmi/getnames.md index d4f6914651424..053b703691aa8 100644 --- a/docs/framework/unmanaged-api/wmi/getnames.md +++ b/docs/framework/unmanaged-api/wmi/getnames.md @@ -41,7 +41,7 @@ HRESULT GetNames ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszQualifierName` [in] A pointer to a valid `LPCWSTR` that specifies a qualifier name that operates as part of a filter. For more information, see the [Remarks](#remarks) section. This parameter can be `null`. @@ -68,7 +68,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetNames](https://msdn.microsoft.com/library/aa391447(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetNames](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getnames) method. The named returned are controlled by a combination of flags and parameters. For example, the function can return the names of all properties or only the names of the key properties. The primary filter is specified in the `lFlags` parameter, and the other parameters vary depending on it. diff --git a/docs/framework/unmanaged-api/wmi/getobjecttext.md b/docs/framework/unmanaged-api/wmi/getobjecttext.md index af880faff15d1..ceda0c0059afa 100644 --- a/docs/framework/unmanaged-api/wmi/getobjecttext.md +++ b/docs/framework/unmanaged-api/wmi/getobjecttext.md @@ -39,7 +39,7 @@ HRESULT GetObjectText ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lFlags` [in] Normally 0. If `WBEM_FLAG_NO_FLAVORS` (or 0x1) is specified, qualifiers are included without propagation or flavor information. @@ -60,7 +60,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetObjectText](https://msdn.microsoft.com/library/aa391448(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetObjectText](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getobjecttext) method. The MOF text returned does not contain all the information about the object, but only enough information for the MOF compiler to be able to recreate the original object. For instance, no propagated qualifiers or parent class properties are included. diff --git a/docs/framework/unmanaged-api/wmi/getpropertyhandle.md b/docs/framework/unmanaged-api/wmi/getpropertyhandle.md index e83869541f269..51de37d9c768a 100644 --- a/docs/framework/unmanaged-api/wmi/getpropertyhandle.md +++ b/docs/framework/unmanaged-api/wmi/getpropertyhandle.md @@ -40,7 +40,7 @@ HRESULT GetPropertyHandle ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemObjectAccess](https://msdn.microsoft.com/library/aa391770(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemObjectAccess](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemobjectaccess) instance. `wszPropertyName` [in] A null-terminated string of UTF16-encoded characaters that contains the property name. @@ -64,9 +64,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetPropertyHandle](https://msdn.microsoft.com/library/aa391771(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetPropertyHandle](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemobjectaccess-getpropertyhandle) method. -You can use this handle to identify properties when using [IWbemObjectAccess](https://msdn.microsoft.com/library/aa391770(v=vs.85).aspx) methods to read or write property values. +You can use this handle to identify properties when using [IWbemObjectAccess](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemobjectaccess) methods to read or write property values. Handles can be retrieved for properties of all data types other than `CIM_OBJECT` and `CIM_ARRAY`. Returned handles work across all instances of a class. diff --git a/docs/framework/unmanaged-api/wmi/getpropertyorigin.md b/docs/framework/unmanaged-api/wmi/getpropertyorigin.md index eb4c725e64f5e..c49fd6b9eeeda 100644 --- a/docs/framework/unmanaged-api/wmi/getpropertyorigin.md +++ b/docs/framework/unmanaged-api/wmi/getpropertyorigin.md @@ -39,7 +39,7 @@ HRESULT GetPropertyOrigin ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszMethodName` [in] The name of the property for the object whose owning class is being requested. @@ -61,7 +61,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetPropertyOrigin](https://msdn.microsoft.com/library/aa391449(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetPropertyOrigin](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getpropertyorigin) method. Because a class can inherit properties from one or more base classes, developers often want to determine the property in which a given method is defined. diff --git a/docs/framework/unmanaged-api/wmi/getpropertyqualifierset.md b/docs/framework/unmanaged-api/wmi/getpropertyqualifierset.md index 8288479d61dc5..66a772f37edf6 100644 --- a/docs/framework/unmanaged-api/wmi/getpropertyqualifierset.md +++ b/docs/framework/unmanaged-api/wmi/getpropertyqualifierset.md @@ -39,7 +39,7 @@ HRESULT GetPropertyQualifierSet ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszMethod` [in] The property name. `wszProperty` must point to a valid `LPCWSTR`. @@ -62,13 +62,13 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetPropertyQualifierSet](https://msdn.microsoft.com/library/aa391450(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetPropertyQualifierSet](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getpropertyqualifierset) method. -A call to this function is supported only if the current object is a CIM class definition. Method manipulation is not available for [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) ponters that point to CIM instances. +A call to this function is supported only if the current object is a CIM class definition. Method manipulation is not available for [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) ponters that point to CIM instances. -Because each method may have its own qualifiers, the [IWbemQualifierSet pointer](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) lets the caller add, edit, or delete these qualifiers. +Because each method may have its own qualifiers, the [IWbemQualifierSet pointer](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) lets the caller add, edit, or delete these qualifiers. -Because system properties have no qualifiers, the function returns `WBEM_E_SYSTEM_PROPERTY` if you attempt to obtain a [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) pointer for a system property. +Because system properties have no qualifiers, the function returns `WBEM_E_SYSTEM_PROPERTY` if you attempt to obtain a [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) pointer for a system property. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/getqualifierset.md b/docs/framework/unmanaged-api/wmi/getqualifierset.md index 7d49b222a2304..3eba4561b8d99 100644 --- a/docs/framework/unmanaged-api/wmi/getqualifierset.md +++ b/docs/framework/unmanaged-api/wmi/getqualifierset.md @@ -38,7 +38,7 @@ HRESULT GetQualifierSet ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `ppQualSet` [out] Receives the interface pointer that allows access to the qualifiers of the class object. `ppQualSet` cannot be `null`. If an error occurs, a new object is not returned, and the pointer is left unmodified. @@ -57,9 +57,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::GetQualifierSet](https://msdn.microsoft.com/library/aa391451(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::GetQualifierSet](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-getqualifierset) method. -The [IWbemQualifierSet pointer](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) lets the caller add, edit, or delete these qualifiers. Such added, edited, or deleted qualifiers apply to the entire instance or class definition. +The [IWbemQualifierSet pointer](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) lets the caller add, edit, or delete these qualifiers. Such added, edited, or deleted qualifiers apply to the entire instance or class definition. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/index.md b/docs/framework/unmanaged-api/wmi/index.md index 7582d2c459532..7b15e69fc44c0 100644 --- a/docs/framework/unmanaged-api/wmi/index.md +++ b/docs/framework/unmanaged-api/wmi/index.md @@ -7,7 +7,7 @@ ms.date: 11/06/2017 --- # Windows Management Instrumentation (WMI) and Performance Counters (Unmanaged API Reference) -The .NET Framework WMI and Performance Counters unmanaged API consists of a set of functions that wrap calls to the [native Windows Management Instrumentation API](https://msdn.microsoft.com/library/aa389276(v=vs.85).aspx). It allows you to develop tools and libraries that manage and monitor remote computer systems. +The .NET Framework WMI and Performance Counters unmanaged API consists of a set of functions that wrap calls to the [native Windows Management Instrumentation API](/windows/desktop/WmiSdk/com-api-for-wmi). It allows you to develop tools and libraries that manage and monitor remote computer systems. [!INCLUDE[internalonly-unmanaged](../../../../includes/internalonly-unmanaged.md)] diff --git a/docs/framework/unmanaged-api/wmi/inheritsfrom.md b/docs/framework/unmanaged-api/wmi/inheritsfrom.md index 566a58ca350c8..7df77a3795427 100644 --- a/docs/framework/unmanaged-api/wmi/inheritsfrom.md +++ b/docs/framework/unmanaged-api/wmi/inheritsfrom.md @@ -38,7 +38,7 @@ HRESULT InheritsFrom ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszAncestor` [in] The name of the class. `wszAncestor` must point to a valid `LPCWSTR`. @@ -55,7 +55,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::InheritsFrom](https://msdn.microsoft.com/library/aa391452(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::InheritsFrom](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-inheritsfrom) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/next.md b/docs/framework/unmanaged-api/wmi/next.md index bf134d55c7559..25a13a2ade69e 100644 --- a/docs/framework/unmanaged-api/wmi/next.md +++ b/docs/framework/unmanaged-api/wmi/next.md @@ -42,7 +42,7 @@ HRESULT Next ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lFlags` [in] Reserved. This parameter must be 0. @@ -75,7 +75,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::Next](https://msdn.microsoft.com/library/aa391453(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::Next](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-next) method. This method also returns system properties. diff --git a/docs/framework/unmanaged-api/wmi/nextmethod.md b/docs/framework/unmanaged-api/wmi/nextmethod.md index 6313a6b63a7d0..ec0ccfe984822 100644 --- a/docs/framework/unmanaged-api/wmi/nextmethod.md +++ b/docs/framework/unmanaged-api/wmi/nextmethod.md @@ -41,7 +41,7 @@ HRESULT NextMethod ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lFlags` [in] Reserved. This parameter must be 0. @@ -50,10 +50,10 @@ HRESULT NextMethod ( [out] A pointer that points to `null` prior to the call. When the function returns, the address of a new `BSTR` that contains the method name. `ppSignatureIn` -[out] A pointer that receives a pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) that contains the `in` parameters for the method. +[out] A pointer that receives a pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) that contains the `in` parameters for the method. `ppSignatureOut` -[out] A pointer that receives a pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) that contains the `out` parameters for the method. +[out] A pointer that receives a pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) that contains the `out` parameters for the method. ## Return value @@ -67,13 +67,13 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::NextMethod](https://msdn.microsoft.com/library/aa391454(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::NextMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-nextmethod) method. The caller begins the enumeration sequence by calling the [BeginMethodEnumeration](beginmethodenumeration.md) function, and then calls the [NextMethod] function until the function returns `WBEM_S_NO_MORE_DATA`. Optionally, the caller finishes the sequence by calling [EndMethodEnumeration](endmethodenumeration.md). The caller may terminate the enumeration early by calling [EndMethodEnumeration](endmethodenumeration.md) at any time. ## Example -For a C++ example, see the [IWbemClassObject::NextMethod](https://msdn.microsoft.com/library/aa391454(v=vs.85).aspx) method. +For a C++ example, see the [IWbemClassObject::NextMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-nextmethod) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/put.md b/docs/framework/unmanaged-api/wmi/put.md index 696331bfb5b5d..0e1a032764f7f 100644 --- a/docs/framework/unmanaged-api/wmi/put.md +++ b/docs/framework/unmanaged-api/wmi/put.md @@ -41,7 +41,7 @@ HRESULT Put ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The name of the property. This parameter cannot be `null`. @@ -71,9 +71,9 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::Put](https://msdn.microsoft.com/library/aa391455(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::Put](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-put) method. -This function always overwrites the current property value with a new one. If the [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) points to a class definition, `Put` creates or updates the property value. When [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) points to a CIM instance, `Put` updates the property value only; `Put` cannot create a property value. +This function always overwrites the current property value with a new one. If the [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) points to a class definition, `Put` creates or updates the property value. When [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) points to a CIM instance, `Put` updates the property value only; `Put` cannot create a property value. The `__CLASS` system property is only writable during class creation, when it may not be left blank. All other system properties are read-only. @@ -85,7 +85,7 @@ Use the `vtType` parameter only when creating new properties in a CIM class defi ## Example -For an example, see the [IWbemClassObject::Put](https://msdn.microsoft.com/library/aa391455(v=vs.85).aspx) method. +For an example, see the [IWbemClassObject::Put](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-put) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/putclasswmi.md b/docs/framework/unmanaged-api/wmi/putclasswmi.md index 6fdbb33ec5978..46a2aeab5ae44 100644 --- a/docs/framework/unmanaged-api/wmi/putclasswmi.md +++ b/docs/framework/unmanaged-api/wmi/putclasswmi.md @@ -54,10 +54,10 @@ HRESULT PutClassWmi ( | `WBEM_FLAG_UPDATE_FORCE_MODE` | 0x40 | forces updates of classes when conflicting child classes exist. For example, this flag forces an update if a class qualifier is defined in a child class, and the base class tries to add the same qualifier which conflicts with thte existing one. In force mode, tis conflict is resolved by deleting the conflicting qualifier in the child class. | `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that can be used by the provider that is providing the requested classes. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that can be used by the provider that is providing the requested classes. `ppCallResult` -[out] If `null`, this parameter is unused. If `lFlags` contains `WBEM_FLAG_RETURN_IMMEDIATELY`, the function returns immediately with `WBEM_S_NO_ERROR`. The `ppCallResult` parameter receives a pointer to a new [IWbemCallResult](https://msdn.microsoft.com/library/aa391425(v=vs.85).aspx) object. +[out] If `null`, this parameter is unused. If `lFlags` contains `WBEM_FLAG_RETURN_IMMEDIATELY`, the function returns immediately with `WBEM_S_NO_ERROR`. The `ppCallResult` parameter receives a pointer to a new [IWbemCallResult](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcallresult) object. ## Return value @@ -81,7 +81,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::PutClass](https://msdn.microsoft.com/library/aa392113(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::PutClass](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-putclass) method. The user may not create classes with names that begin or end with an underscore chacater diff --git a/docs/framework/unmanaged-api/wmi/putinstancewmi.md b/docs/framework/unmanaged-api/wmi/putinstancewmi.md index 664b456745971..87cbf28f2e4b4 100644 --- a/docs/framework/unmanaged-api/wmi/putinstancewmi.md +++ b/docs/framework/unmanaged-api/wmi/putinstancewmi.md @@ -50,10 +50,10 @@ HRESULT PutInstanceWmi ( | `WBEM_FLAG_RETURN_IMMEDIATELY` | 0x10 | The flag causes a semisynchronous call. | `pCtx` -[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](https://msdn.microsoft.com/library/aa391465(v=vs.85).aspx) instance that can be used by the provider that is providing the requested classes. +[in] Typically, this value is `null`. Otherwise, it is a pointer to an [IWbemContext](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcontext) instance that can be used by the provider that is providing the requested classes. `ppCallResult` -[out] If `null`, this parameter is unused. If `lFlags` contains `WBEM_FLAG_RETURN_IMMEDIATELY`, the function returns immediately with `WBEM_S_NO_ERROR`. The `ppCallResult` parameter receives a pointer to a new [IWbemCallResult](https://msdn.microsoft.com/library/aa391425(v=vs.85).aspx) object. +[out] If `null`, this parameter is unused. If `lFlags` contains `WBEM_FLAG_RETURN_IMMEDIATELY`, the function returns immediately with `WBEM_S_NO_ERROR`. The `ppCallResult` parameter receives a pointer to a new [IWbemCallResult](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemcallresult) object. ## Return value @@ -76,7 +76,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemServices::PutInstance](https://msdn.microsoft.com/library/aa392115(v=vs.85).aspx) method. +This function wraps a call to the [IWbemServices::PutInstance](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemservices-putinstance) method. The `PutInstanceWmi` function supports creating instances and updating instances of existing classes only. Depending on how the `pCtx` parameter is set, either some or all of the properties of the instance are updated. diff --git a/docs/framework/unmanaged-api/wmi/putmethod.md b/docs/framework/unmanaged-api/wmi/putmethod.md index 2224835361fe3..81a7fe0972daa 100644 --- a/docs/framework/unmanaged-api/wmi/putmethod.md +++ b/docs/framework/unmanaged-api/wmi/putmethod.md @@ -41,7 +41,7 @@ HRESULT PutMethod ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `wszName` [in] The name of the method to create. @@ -50,10 +50,10 @@ HRESULT PutMethod ( [in] Reserved. This parameter must be 0. `pSignatureIn` -[in] A pointer to a copy of the [__Parameters system class](https://msdn.microsoft.com/library/aa394667(v=vs.85).aspx) that contains the `in` parameters for the method. This parameter is ignored if set to `null`. +[in] A pointer to a copy of the [__Parameters system class](/windows/desktop/WmiSdk/--parameters) that contains the `in` parameters for the method. This parameter is ignored if set to `null`. `pSignatureOut` -[in] A pointer to a copy of the [__Parameters system class](https://msdn.microsoft.com/library/aa394667(v=vs.85).aspx) that contains the `out` parameters for the method. This parameter is ignored if set to `null`. +[in] A pointer to a copy of the [__Parameters system class](/windows/desktop/WmiSdk/--parameters) that contains the `out` parameters for the method. This parameter is ignored if set to `null`. ## Return value @@ -72,7 +72,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::PutMethod](https://msdn.microsoft.com/library/aa391456(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::PutMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-putmethod) method. This method call is only supported if `ptr` is a CIM class definition. Method manipulation is not available from [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx?f=255&MSPPError=-2147217396) pointers that point to CIM instances. @@ -82,11 +82,11 @@ For a method, the `in` and `out` parameters are described as properties in [IWbe An `[in/out]` parameter can be defined by adding the same property to both objects pointed to by the `pInSignature` and `pOutSignature` parameters. In this case, the properties share the same **ID** qualifier value. -Each property in a [__Parameters](https://msdn.microsoft.com/library/aa394667(v=vs.85).aspx) class object other than `ReturnValue` must have an **ID** qualifier, a zero-based numeric value that identifies the order in which the parameters appear. No two parameters can have the same **ID** value, and no **ID** value can be skipped. If either condition occurs, the `PutMethod` function returns `WBEM_E_NONCONSECUTIVE_PARAMETER_IDS`. +Each property in a [__Parameters](/windows/desktop/WmiSdk/--parameters) class object other than `ReturnValue` must have an **ID** qualifier, a zero-based numeric value that identifies the order in which the parameters appear. No two parameters can have the same **ID** value, and no **ID** value can be skipped. If either condition occurs, the `PutMethod` function returns `WBEM_E_NONCONSECUTIVE_PARAMETER_IDS`. ## Example -For an example, see the [IWbemClassObject::PutMethod](https://msdn.microsoft.com/library/aa391456(v=vs.85).aspx) method. +For an example, see the [IWbemClassObject::PutMethod](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-putmethod) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-beginenumeration.md b/docs/framework/unmanaged-api/wmi/qualifierset-beginenumeration.md index 768265c90cca8..d0f25da0013f9 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-beginenumeration.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-beginenumeration.md @@ -38,7 +38,7 @@ HRESULT QualifierSet_BeginEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `lFlags` [in] A bitwise combination of the flags or values described in the [Remarks](#remarks) section that specifies the qualifiers to include in the enumeration. @@ -56,7 +56,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::BeginEnumeration](https://msdn.microsoft.com/library/aa391861(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::BeginEnumeration](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-beginenumeration) method. To enumerate all of the qualifiers on an object, this method must be called before the first call to [QualifierSet_Next](qualifierset-next.md). The order in which qualifiers are enumerated is guaranteed to be invariant for a given enumeration. diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-delete.md b/docs/framework/unmanaged-api/wmi/qualifierset-delete.md index 221979bee0063..fd72b86feb288 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-delete.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-delete.md @@ -38,7 +38,7 @@ HRESULT QualifierSet_Delete ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `wszName` [in] The name of the qualifier to delete. @@ -57,7 +57,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::Delete](https://msdn.microsoft.com/library/aa391864(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::Delete](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-delete) method. Due to qualifier propagation rules, a particular qualifier may have been inherited from another object and merely overridden in the current class or instance. In this case, the `QualifierSet_Delete` method resets the qualifier to its original inherited value. The function in this case returns the status code `WBEM_S_RESET_TO_DEFAULT`. diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-endenumeration.md b/docs/framework/unmanaged-api/wmi/qualifierset-endenumeration.md index bdf35c6846a7c..73a330b58bf8b 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-endenumeration.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-endenumeration.md @@ -37,7 +37,7 @@ HRESULT QualifierSet_EndEnumeration ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. ## Return value @@ -49,7 +49,7 @@ The following value returned by this function is defined in the *WbemCli.h* head ## Remarks -This function wraps a call to the [IWbemQualifierSet::EndEnumeration](https://msdn.microsoft.com/library/aa391865(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::EndEnumeration](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-endenumeration) method. This call is recommended, but not required. It immediately releases resources associated with the enumeration. diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-get.md b/docs/framework/unmanaged-api/wmi/qualifierset-get.md index c7e257d3e2f24..f2597648e6184 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-get.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-get.md @@ -41,7 +41,7 @@ HRESULT QualifierSet_Get ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `wszName` [in] The name of the qualifier whose value is requested. @@ -67,7 +67,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::Get](https://msdn.microsoft.com/library/aa391867(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::Get](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-get) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-getnames.md b/docs/framework/unmanaged-api/wmi/qualifierset-getnames.md index cc60713b3eb87..b91e20344bfd4 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-getnames.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-getnames.md @@ -39,7 +39,7 @@ HRESULT QualifierSet_GetNames ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `lFlags` [in] One of the following flags or values that specifies which names to include in the enumeration. @@ -65,7 +65,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::GetNames](https://msdn.microsoft.com/library/aa391868(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::GetNames](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-getnames) method. Once you've retrieved the qualifier names, you can access each qualifier by name by calling the [QualifierSet_Get](qualifierset-get.md) function. diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-next.md b/docs/framework/unmanaged-api/wmi/qualifierset-next.md index dbeb8f6f3ae70..32ac2b8db267a 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-next.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-next.md @@ -41,7 +41,7 @@ HRESULT QualifierSet_Next ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `lFlags` [in] Reserved. This parameter must be 0. @@ -69,7 +69,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::Next](https://msdn.microsoft.com/library/aa391870(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::Next](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-next) method. You call the `QualifierSet_Next` function repeatedly to enumerate all the qualifiers until the function return `WBEM_S_NO_MORE_DATA`. To terminate the enumeration early, call the [QualifierSet_EndEnumeration](qualifierset-endenumeration.md) function. diff --git a/docs/framework/unmanaged-api/wmi/qualifierset-put.md b/docs/framework/unmanaged-api/wmi/qualifierset-put.md index d19f61f2410f2..ddad805a8ff35 100644 --- a/docs/framework/unmanaged-api/wmi/qualifierset-put.md +++ b/docs/framework/unmanaged-api/wmi/qualifierset-put.md @@ -40,7 +40,7 @@ HRESULT QualifierSet_Put ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemQualifierSet](https://msdn.microsoft.com/library/aa391860(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemQualifierSet](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemqualifierset) instance. `wszName` [in] The name of the qualifier to write. @@ -73,7 +73,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemQualifierSet::Put](https://msdn.microsoft.com/library/aa391871(v=vs.85).aspx) method. +This function wraps a call to the [IWbemQualifierSet::Put](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemqualifierset-put) method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/wmi/spawnderivedclass.md b/docs/framework/unmanaged-api/wmi/spawnderivedclass.md index fc9f6aef058fc..15b391134e5f5 100644 --- a/docs/framework/unmanaged-api/wmi/spawnderivedclass.md +++ b/docs/framework/unmanaged-api/wmi/spawnderivedclass.md @@ -38,7 +38,7 @@ HRESULT SpawnDerivedClass ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lFlags` [in] Reserved. This parameter must be 0. @@ -61,7 +61,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::SpawnDerivedClass](https://msdn.microsoft.com/library/aa391436(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::SpawnDerivedClass](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-clone) method. `ptr` must be a class definition that becomes the parent class of the spawned object. The returned object becomes a subclass of the current object. diff --git a/docs/framework/unmanaged-api/wmi/spawninstance.md b/docs/framework/unmanaged-api/wmi/spawninstance.md index 274c3a4753b0b..0304025091d8b 100644 --- a/docs/framework/unmanaged-api/wmi/spawninstance.md +++ b/docs/framework/unmanaged-api/wmi/spawninstance.md @@ -38,7 +38,7 @@ HRESULT SpawnInstance ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemClassObject](https://msdn.microsoft.com/library/aa391433%28v=vs.85%29.aspx) instance. +[in] A pointer to an [IWbemClassObject](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemclassobject) instance. `lFlags` [in] Reserved. This parameter must be 0. @@ -59,7 +59,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::SpawnInstance](https://msdn.microsoft.com/library/aa391458(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::SpawnInstance](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemclassobject-spawninstance) method. `ptr` must be a class definition obtained from Windows Management. (Note that spawning an instance from an instance is supported but the returned instance is empty.) You then use this class definition to create new instances. A call to the [PutInstanceWmi](putinstancewmi.md) function is required if you intend to write the instance to Windows Management. diff --git a/docs/framework/unmanaged-api/wmi/writepropertyvalue.md b/docs/framework/unmanaged-api/wmi/writepropertyvalue.md index 6582cbd45cbd1..d59307cc08294 100644 --- a/docs/framework/unmanaged-api/wmi/writepropertyvalue.md +++ b/docs/framework/unmanaged-api/wmi/writepropertyvalue.md @@ -40,7 +40,7 @@ HRESULT WritePropertyValue ( [in] This parameter is unused. `ptr` -[in] A pointer to an [IWbemObjectAccess](https://msdn.microsoft.com/library/aa391770(v=vs.85).aspx) instance. +[in] A pointer to an [IWbemObjectAccess](/windows/desktop/api/wbemcli/nn-wbemcli-iwbemobjectaccess) instance. `lHandle` [in] An integer that contains the handle that identifies this property. The handle can be retrieved by calling the [GetPropertyHandle](getpropertyhandle.md) function. @@ -63,7 +63,7 @@ The following values returned by this function are defined in the *WbemCli.h* he ## Remarks -This function wraps a call to the [IWbemClassObject::WritePropertyValue](https://msdn.microsoft.com/library/aa391783(v=vs.85).aspx) method. +This function wraps a call to the [IWbemClassObject::WritePropertyValue](/windows/desktop/api/wbemcli/nf-wbemcli-iwbemobjectaccess-writepropertyvalue) method. Use this function to set string and all other non-`DWORD` or non-`QWORD` data. diff --git a/docs/framework/wcf/diagnostics/wmi/index.md b/docs/framework/wcf/diagnostics/wmi/index.md index 0a1bb948d0cc9..64973982a809f 100644 --- a/docs/framework/wcf/diagnostics/wmi/index.md +++ b/docs/framework/wcf/diagnostics/wmi/index.md @@ -7,7 +7,7 @@ ms.assetid: fe48738d-e31b-454d-b5ec-24c85c6bf79a Windows Communication Foundation (WCF) exposes inspection data of a service at runtime through a WCF Windows Management Instrumentation (WMI) provider. ## Enabling WMI - WMI is Microsoft's implementation of the Web-Based Enterprise Management (WBEM) standard. For more information about the WMI SDK, see [Windows Management Instrumentation](https://msdn.microsoft.com/library/aa394582.aspx). WBEM is an industry standard for how applications expose management instrumentation to external management tools. + WMI is Microsoft's implementation of the Web-Based Enterprise Management (WBEM) standard. For more information about the WMI SDK, see [Windows Management Instrumentation](/windows/desktop/WmiSdk/wmi-start-page). WBEM is an industry standard for how applications expose management instrumentation to external management tools. A WMI provider is a component that exposes instrumentation at runtime through a WBEM-compatible interface. It consists of a set of WMI objects that have attribute/value pairs. Pairs can be of a number of simple types. Management tools can connect to the services through the interface at runtime. WCF exposes attributes of services such as addresses, bindings, behaviors, and listeners. diff --git a/docs/framework/wcf/feature-details/error-handling.md b/docs/framework/wcf/feature-details/error-handling.md index 7c29bad244923..8f04ed52271cc 100644 --- a/docs/framework/wcf/feature-details/error-handling.md +++ b/docs/framework/wcf/feature-details/error-handling.md @@ -55,11 +55,11 @@ ms.assetid: c948841a-7db9-40ae-9b78-587d216cbcaf ### URI template errors when using WebGetAttribute and WebInvokeAttribute The WebGet and WebInvoke attributes allow you to specify a URI template that maps components of the request address to operation parameters. For example, the URI template "weather/{state}/{city}" maps the request address into literal tokens, a parameter named state, and a parameter named city. These parameters might then be bound by name to some of the formal parameters of the operation. - The template parameters appear in the form of strings within the URI while the formal parameters of a typed contract might be of non-string types. Therefore, a conversion needs to take place before the operation can be invoked. A [table of conversion formats](http://msdn.microsoft.com/library/bb412172.aspx) is available. + The template parameters appear in the form of strings within the URI while the formal parameters of a typed contract might be of non-string types. Therefore, a conversion needs to take place before the operation can be invoked. A [table of conversion formats](wcf-web-http-programming-model-overview.md) is available. However, if the conversion fails, then there's no way to let the operation know that something has gone wrong. The type conversion instead surfaces in the form of a dispatch failure. A type conversion dispatch failure can be inspected the same as with many other types of dispatch failures by installing an error handler. The IErrorHandler extensibility point is called to handle service-level exceptions. From there, the response to be sent back to the caller – as well as perform any custom tasks and reporting – may be chosen. ## See Also - [Basic WCF Error Handling](http://msdn.microsoft.com/library/gg281715.aspx) + [Basic WCF Programming](../basic-wcf-programming.md) diff --git a/docs/framework/wcf/samples/wmi-provider.md b/docs/framework/wcf/samples/wmi-provider.md index ea7a14b91ffa9..84bd3456f40e8 100644 --- a/docs/framework/wcf/samples/wmi-provider.md +++ b/docs/framework/wcf/samples/wmi-provider.md @@ -6,7 +6,7 @@ ms.assetid: 462f0db3-f4a4-4a4b-ac26-41fc25c670a4 # WMI Provider This sample demonstrates how to gather data from Windows Communication Foundation (WCF) services at runtime by using the Windows Management Instrumentation (WMI) provider that is built into WCF. Also, this sample demonstrates how to add a user-defined WMI object to a service. The sample activates the WMI provider for the [Getting Started](../../../../docs/framework/wcf/samples/getting-started-sample.md) and demonstrates how to gather data from the `ICalculator` service at runtime. - WMI is Microsoft's implementation of the Web-Based Enterprise Management (WBEM) standard. For more information about the WMI SDK, see [Windows Management Instrumentation](https://msdn.microsoft.com/library/aa394582.aspx). WBEM is an industry standard for how applications expose management instrumentation to external management tools. + WMI is Microsoft's implementation of the Web-Based Enterprise Management (WBEM) standard. For more information about the WMI SDK, see [Windows Management Instrumentation](/windows/desktop/WmiSdk/wmi-start-page). WBEM is an industry standard for how applications expose management instrumentation to external management tools. WCF implements a WMI provider, a component that exposes instrumentation at runtime through a WBEM-compatible interface. Management tools can connect to the services through the interface at runtime. WCF exposes attributes of services such as addresses, bindings, behaviors, and listeners. diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index bec70f4326f66..8efbb508b7a94 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -598,7 +598,7 @@ In the .NET Framework 4.7, WPF includes the following enhancements: **Support for a touch/stylus stack based on Windows WM_POINTER messages** -You now have the option of using a touch/stylus stack based on [WM_POINTER messages](https://msdn.microsoft.com/library/windows/desktop/hh454903.aspx) instead of the Windows Ink Services Platform (WISP). This is an opt-in feature in the .NET Framework. For more information, see [Retargeting Changes in the .NET Framework 4.7](../migration-guide/retargeting-changes-in-the-net-framework-4-7.md). +You now have the option of using a touch/stylus stack based on [WM_POINTER messages](https://docs.microsoft.com/previous-versions/windows/desktop/InputMsg/messages) instead of the Windows Ink Services Platform (WISP). This is an opt-in feature in the .NET Framework. For more information, see [Retargeting Changes in the .NET Framework 4.7](../migration-guide/retargeting-changes-in-the-net-framework-4-7.md). **New implementation for WPF printing APIs** @@ -1298,7 +1298,7 @@ SqlClient now automatically provides faster connections to an AlwaysOn Availabil - **Cryptography updates** - The API is being updated to support the [Windows CNG cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa376214.aspx). Previous versions of the .NET Framework have relied entirely on an [earlier version of the Windows Cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa380255.aspx) as the basis for the implementation. We have had requests to support the CNG API, since it supports [modern cryptography algorithms](https://msdn.microsoft.com/library/windows/desktop/bb204775.aspx#suite_b_support), which are important for certain categories of apps. + The API is being updated to support the [Windows CNG cryptography APIs](/windows/desktop/SecCNG/cng-reference). Previous versions of the .NET Framework have relied entirely on an [earlier version of the Windows Cryptography APIs](/windows/desktop/SecCrypto/cryptography-portal) as the basis for the implementation. We have had requests to support the CNG API, since it supports [modern cryptography algorithms](https://msdn.microsoft.com/library/windows/desktop/bb204775.aspx#suite_b_support), which are important for certain categories of apps. The .NET Framework 4.6 includes the following new enhancements to support the Windows CNG cryptography APIs: @@ -1503,7 +1503,7 @@ SqlClient now automatically provides faster connections to an AlwaysOn Availabil - The property. - By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](https://msdn.microsoft.com/library/windows/desktop/ms740532.aspx), that enables local port reuse. + By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](/windows/desktop/WinSock/sol-socket-socket-options), that enables local port reuse. Developers writing a sockets-only application can specify the option when calling a method such as so that outbound sockets reuse local ports during binding. diff --git a/docs/framework/windows-services/how-to-debug-windows-service-applications.md b/docs/framework/windows-services/how-to-debug-windows-service-applications.md index ff9e79913798b..b62c98d67bfcf 100644 --- a/docs/framework/windows-services/how-to-debug-windows-service-applications.md +++ b/docs/framework/windows-services/how-to-debug-windows-service-applications.md @@ -27,7 +27,7 @@ A service must be run from within the context of the Services Control Manager ra > Debugging the method can be difficult because the Services Control Manager imposes a 30-second limit on all attempts to start a service. For more information, see [Troubleshooting: Debugging Windows Services](../../../docs/framework/windows-services/troubleshooting-debugging-windows-services.md). > [!WARNING] -> To get meaningful information for debugging, the Visual Studio debugger needs to find symbol files for the binaries that are being debugged. If you are debugging a service that you built in Visual Studio, the symbol files (.pdb files) are in the same folder as the executable or library, and the debugger loads them automatically. If you are debugging a service that you didn't build, you should first find symbols for the service and make sure they can be found by the debugger. See [Specify Symbol (.pdb) and Source Files](http://msdn.microsoft.com/library/1105e169-5272-4e7c-b3e7-cda1b7798a6b). If you're debugging a system process or want to have symbols for system calls in your services, you should add the Microsoft Symbol Servers. See [Debugging Symbols](http://msdn.microsoft.com/windows/desktop/ee416588.aspx). +> To get meaningful information for debugging, the Visual Studio debugger needs to find symbol files for the binaries that are being debugged. If you are debugging a service that you built in Visual Studio, the symbol files (.pdb files) are in the same folder as the executable or library, and the debugger loads them automatically. If you are debugging a service that you didn't build, you should first find symbols for the service and make sure they can be found by the debugger. See [Specify Symbol (.pdb) and Source Files](http://msdn.microsoft.com/library/1105e169-5272-4e7c-b3e7-cda1b7798a6b). If you're debugging a system process or want to have symbols for system calls in your services, you should add the Microsoft Symbol Servers. See [Debugging Symbols](/windows/desktop/DxTechArts/debugging-with-symbols). ### To debug a service @@ -112,4 +112,4 @@ A service must be run from within the context of the Services Control Manager ra [Introduction to Windows Service Applications](../../../docs/framework/windows-services/introduction-to-windows-service-applications.md) [How to: Install and Uninstall Services](../../../docs/framework/windows-services/how-to-install-and-uninstall-services.md) [How to: Start Services](../../../docs/framework/windows-services/how-to-start-services.md) - [Debugging a Service](http://msdn.microsoft.com/library/windows/desktop/ms682546.aspx) + [Debugging a Service](/windows/desktop/Services/debugging-a-service) diff --git a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md index e8728c0f9c2c8..a89681aa5167e 100644 --- a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md +++ b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md @@ -155,7 +155,7 @@ This article demonstrates how to create a simple Windows Service application in ## Setting Service Status - Services report their status to the Service Control Manager, so that users can tell whether a service is functioning correctly. By default, services that inherit from report a limited set of status settings, including Stopped, Paused, and Running. If a service takes a little while to start up, it might be helpful to report a Start Pending status. You can also implement the Start Pending and Stop Pending status settings by adding code that calls into the Windows [SetServiceStatus function](http://msdn.microsoft.com/library/windows/desktop/ms686241.aspx). + Services report their status to the Service Control Manager, so that users can tell whether a service is functioning correctly. By default, services that inherit from report a limited set of status settings, including Stopped, Paused, and Running. If a service takes a little while to start up, it might be helpful to report a Start Pending status. You can also implement the Start Pending and Stop Pending status settings by adding code that calls into the Windows [SetServiceStatus function](/windows/desktop/api/winsvc/nf-winsvc-setservicestatus). #### To implement service pending status @@ -219,7 +219,7 @@ This article demonstrates how to create a simple Windows Service application in End Structure ``` -3. Now, in the `MyNewService` class, declare the [SetServiceStatus function](http://msdn.microsoft.com/library/windows/desktop/ms686241.aspx) by using platform invoke: +3. Now, in the `MyNewService` class, declare the [SetServiceStatus function](/windows/desktop/api/winsvc/nf-winsvc-setservicestatus) by using platform invoke: ```csharp [DllImport("advapi32.dll", SetLastError=true)] @@ -265,7 +265,7 @@ This article demonstrates how to create a simple Windows Service application in 6. (Optional) Repeat this procedure for the method. > [!CAUTION] -> The [Service Control Manager](http://msdn.microsoft.com/library/windows/desktop/ms685150.aspx) uses the `dwWaitHint` and `dwCheckpoint` members of the [SERVICE_STATUS structure](http://msdn.microsoft.com/library/windows/desktop/ms685996.aspx) to determine how much time to wait for a Windows Service to start or shut down. If your and methods run long, your service can request more time by calling [SetServiceStatus](http://msdn.microsoft.com/library/windows/desktop/ms686241.aspx) again with an incremented `dwCheckPoint` value. +> The [Service Control Manager](/windows/desktop/Services/service-control-manager) uses the `dwWaitHint` and `dwCheckpoint` members of the [SERVICE_STATUS structure](/windows/desktop/api/winsvc/ns-winsvc-_service_status) to determine how much time to wait for a Windows Service to start or shut down. If your and methods run long, your service can request more time by calling [SetServiceStatus](/windows/desktop/api/winsvc/nf-winsvc-setservicestatus) again with an incremented `dwCheckPoint` value. ## Adding Installers to the Service diff --git a/docs/framework/wpf/advanced/cleartype-registry-settings.md b/docs/framework/wpf/advanced/cleartype-registry-settings.md index 2fbd358dbf96c..89af0effbb506 100644 --- a/docs/framework/wpf/advanced/cleartype-registry-settings.md +++ b/docs/framework/wpf/advanced/cleartype-registry-settings.md @@ -110,4 +110,4 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../.. ## See Also [ClearType Overview](../../../../docs/framework/wpf/advanced/cleartype-overview.md) - [ClearType Antialiasing](https://msdn.microsoft.com/library/dd183433(v=vs.85).aspx) + [ClearType Antialiasing](/windows/desktop/gdi/cleartype-antialiasing) diff --git a/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md b/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md index 275234400bb2b..d573d3c2a5375 100644 --- a/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md +++ b/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md @@ -26,8 +26,8 @@ There are essentially three platforms that support digital ink: the Tablet PC Wi |To do this…|On the WPF Platform…|On the Windows Forms/COM Platforms…| |-----------------|--------------------------|------------------------------------------| -|Add an ink-enabled control to an application|See [Getting Started with Ink](../../../../docs/framework/wpf/advanced/getting-started-with-ink.md).|See [Auto Claims Form Sample](http://msdn.microsoft.com/bec4333a-62ca-4254-a39b-04bc2c556992)| -|Enable ink on a custom control|See [Creating an Ink Input Control](../../../../docs/framework/wpf/advanced/creating-an-ink-input-control.md).|See [Ink Clipboard Sample](http://msdn.microsoft.com/a0c42f1c-543d-44f8-83d9-fe810de410ff).| +|Add an ink-enabled control to an application|See [Getting Started with Ink](../../../../docs/framework/wpf/advanced/getting-started-with-ink.md).|See [Auto Claims Form Sample](/windows/desktop/tablet/auto-claims-form-sample)| +|Enable ink on a custom control|See [Creating an Ink Input Control](../../../../docs/framework/wpf/advanced/creating-an-ink-input-control.md).|See [Ink Clipboard Sample](/windows/desktop/tablet/ink-clipboard-sample).| ## Ink Data On the Windows Forms and COM platforms, [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx), [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx), [Microsoft.Ink.InkEdit](https://msdn.microsoft.com/library/ms835842.aspx), and [Microsoft.Ink.InkPicture](https://msdn.microsoft.com/library/aa514604.aspx) each expose a [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=nameWithType) object. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object contains the data for one or more [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx?displayProperty=nameWithType) objects and exposes common methods and properties to manage and manipulate those strokes. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object manages the lifetime of the strokes it contains; the [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object creates and deletes the strokes that it owns. Each [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx) has an identifier that is unique within its parent [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object. @@ -78,7 +78,7 @@ There are essentially three platforms that support digital ink: the Tablet PC Wi [!code-csharp[WinFormWPFInk#LoadWinforms](../../../../samples/snippets/csharp/VS_Snippets_Wpf/WinformWPFInk/CSharp/Program.cs#loadwinforms)] [!code-vb[WinFormWPFInk#LoadWinforms](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/WinformWPFInk/VisualBasic/Module1.vb#loadwinforms)] ## Events from the Tablet Pen - The [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx), [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx), and [Microsoft.Ink.InkPicture](https://msdn.microsoft.com/library/aa514604.aspx) on the Windows Forms and COM platforms receive events when the user inputs pen data. The [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx) or [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx) is attached to a window or a control, and can subscribe to the events raised by the tablet input data. The thread on which these events occurs depends on whether the events are raised with a pen, a mouse, or programmatically. For more information about threading in relation to these events, see [General Threading Considerations](http://msdn.microsoft.com/cf35724f-5f80-4b3e-992a-a9d5ea99aae9) and [Threads on Which an Event Can Fire](http://msdn.microsoft.com/d1a5ab9b-d474-4ed7-9aa8-b5bdb771934f). + The [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx), [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx), and [Microsoft.Ink.InkPicture](https://msdn.microsoft.com/library/aa514604.aspx) on the Windows Forms and COM platforms receive events when the user inputs pen data. The [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx) or [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx) is attached to a window or a control, and can subscribe to the events raised by the tablet input data. The thread on which these events occurs depends on whether the events are raised with a pen, a mouse, or programmatically. For more information about threading in relation to these events, see [General Threading Considerations](/windows/desktop/tablet/general-threading-considerations) and [Threads on Which an Event Can Fire](/windows/desktop/tablet/threads-on-which-an-event-can-fire). On the Windows Presentation Foundation platform, the class has events for pen input. This means that every control exposes the full set of stylus events. The stylus events have tunneling/bubbling event pairs and always occur on the application thread. For more information, see [Routed Events Overview](../../../../docs/framework/wpf/advanced/routed-events-overview.md). @@ -87,11 +87,11 @@ There are essentially three platforms that support digital ink: the Tablet PC Wi ![Diagram of the Stylus events in WPF vs Winforms.](../../../../docs/framework/wpf/advanced/media/ink-stylusevents.png "Ink_StylusEvents") ## Pen Data - All three platforms provide you with ways to intercept and manipulate the data that comes in from a tablet pen. On the Windows Forms and COM Platforms, this is achieved by creating a [Microsoft.StylusInput.RealTimeStylus](https://msdn.microsoft.com/library/microsoft.stylusinput.realtimestylus(v=vs.100).aspx), attaching a window or control to it, and creating a class that implements the [Microsoft.StylusInput.IStylusSyncPlugin](https://msdn.microsoft.com/library/microsoft.stylusinput.istylussyncplugin(v=vs.100).aspx) or [Microsoft.StylusInput.IStylusAsyncPlugin](https://msdn.microsoft.com/library/microsoft.stylusinput.istylusasyncplugin(v=vs.100).aspx) interface. The custom plug-in is then added to the plug-in collection of the [Microsoft.StylusInput.RealTimeStylus](https://msdn.microsoft.com/library/microsoft.stylusinput.realtimestylus(v=vs.100).aspx). For more information about this object model, see [Architecture of the StylusInput APIs](http://msdn.microsoft.com/88bab0ab-df9f-4813-9a9f-9a137813f0b4). + All three platforms provide you with ways to intercept and manipulate the data that comes in from a tablet pen. On the Windows Forms and COM Platforms, this is achieved by creating a [Microsoft.StylusInput.RealTimeStylus](https://msdn.microsoft.com/library/microsoft.stylusinput.realtimestylus(v=vs.100).aspx), attaching a window or control to it, and creating a class that implements the [Microsoft.StylusInput.IStylusSyncPlugin](https://msdn.microsoft.com/library/microsoft.stylusinput.istylussyncplugin(v=vs.100).aspx) or [Microsoft.StylusInput.IStylusAsyncPlugin](https://msdn.microsoft.com/library/microsoft.stylusinput.istylusasyncplugin(v=vs.100).aspx) interface. The custom plug-in is then added to the plug-in collection of the [Microsoft.StylusInput.RealTimeStylus](https://msdn.microsoft.com/library/microsoft.stylusinput.realtimestylus(v=vs.100).aspx). For more information about this object model, see [Architecture of the StylusInput APIs](/windows/desktop/tablet/architecture-of-the-stylusinput-apis). On the [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] platform, the class exposes a collection of plug-ins, similar in design to the [Microsoft.StylusInput.RealTimeStylus](https://msdn.microsoft.com/library/microsoft.stylusinput.realtimestylus(v=vs.100).aspx). To intercept pen data, create a class that inherits from and add the object to the collection of the . For more information about this interaction, see [Intercepting Input from the Stylus](../../../../docs/framework/wpf/advanced/intercepting-input-from-the-stylus.md). - On all platforms, a thread pool receives the ink data via stylus events and sends it to the application thread. For more information about threading on the COM and Windows Platforms, see [Threading Considerations for the StylusInput APIs](http://msdn.microsoft.com/5d98768a-c60b-4bb0-8640-9bf38254d41f). For more information about threading on the Windows Presentation Software, see [The Ink Threading Model](../../../../docs/framework/wpf/advanced/the-ink-threading-model.md). + On all platforms, a thread pool receives the ink data via stylus events and sends it to the application thread. For more information about threading on the COM and Windows Platforms, see [Threading Considerations for the StylusInput APIs](/windows/desktop/tablet/threading-considerations-for-the-stylusinput-apis). For more information about threading on the Windows Presentation Software, see [The Ink Threading Model](../../../../docs/framework/wpf/advanced/the-ink-threading-model.md). The following illustration compares the object models for the classes that receive pen data on the pen thread pool. diff --git a/docs/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md b/docs/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md index 1f783b403a2c2..54a3a1502c392 100644 --- a/docs/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md +++ b/docs/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md @@ -35,7 +35,7 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc 3. Set the threading model to single-threaded apartment (STA). -4. Handle the [WM_CREATE](http://msdn.microsoft.com/library/ms632619.aspx)notification in your window procedure and do the following: +4. Handle the [WM_CREATE](/windows/desktop/winmsg/wm-create)notification in your window procedure and do the following: 1. Create a new object with the parent window as its `parent` parameter. @@ -112,7 +112,7 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ### Hosting the WPF Content The [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] content is a simple address entry application. It consists of several controls to take user name, address, and so on. There are also two controls, **OK** and **Cancel**. When the user clicks **OK**, the button's event handler collects the data from the controls, assigns it to corresponding properties, and raises a custom event, `OnButtonClicked`. When the user clicks **Cancel**, the handler simply raises `OnButtonClicked`. The event argument object for `OnButtonClicked` contains a Boolean field that indicates which button was clicked. - The code to host the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] content is implemented in a handler for the [WM_CREATE](http://msdn.microsoft.com/library/ms632619.aspx) notification on the host window. + The code to host the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] content is implemented in a handler for the [WM_CREATE](/windows/desktop/winmsg/wm-create) notification on the host window. [!code-cpp[Win32HostingWPFPage#WMCreate](../../../../samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#wmcreate)] diff --git a/docs/framework/wpf/getting-started/index.md b/docs/framework/wpf/getting-started/index.md index 3905632e4902c..4fc4549a26f04 100644 --- a/docs/framework/wpf/getting-started/index.md +++ b/docs/framework/wpf/getting-started/index.md @@ -16,7 +16,7 @@ Windows Presentation Foundation (WPF) is a UI framework that creates desktop cli |-|-| |I want to jump right in…|[Walkthrough: My first WPF desktop application](../../../../docs/framework/wpf/getting-started/walkthrough-my-first-wpf-desktop-application.md)| |How do I design the application UI?|[Designing XAML in Visual Studio](/visualstudio/designers/designing-xaml-in-visual-studio)| -|New to .NET?|[Overview of the .NET Framework](https://msdn.microsoft.com/library/zw4w595w\(v=vs.140\).aspx)

[.NET Framework Application Essentials](../../../../docs/standard/application-essentials.md)

[Getting Started with Visual C# and Visual Basic](https://msdn.microsoft.com/library/dd492171\(v=vs.140\).aspx)| +|New to .NET?|[Overview of the .NET Framework](https://msdn.microsoft.com/library/zw4w595w\(v=vs.140\).aspx)

[.NET Framework Application Essentials](../../../../docs/standard/application-essentials.md)

[Getting Started with Visual C# and Visual Basic](/visualstudio/ide/getting-started-with-visual-csharp-and-visual-basic)| |Tell me more about WPF…|[Introduction to WPF in Visual Studio](../../../../docs/framework/wpf/getting-started/introduction-to-wpf-in-vs.md)

[XAML Overview (WPF)](../../../../docs/framework/wpf/advanced/xaml-overview-wpf.md)

[Controls](../../../../docs/framework/wpf/controls/index.md)

[Data Binding Overview](../../../../docs/framework/wpf/data/data-binding-overview.md)| |Are you a Windows Forms developer?|[Windows Forms Controls and Equivalent WPF Controls](../../../../docs/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md)

[WPF and Windows Forms Interoperation](../../../../docs/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md)| diff --git a/docs/framework/wpf/graphics-multimedia/bitmap-effects-overview.md b/docs/framework/wpf/graphics-multimedia/bitmap-effects-overview.md index 5bb19d76c8ad2..5b71aadfc5e29 100644 --- a/docs/framework/wpf/graphics-multimedia/bitmap-effects-overview.md +++ b/docs/framework/wpf/graphics-multimedia/bitmap-effects-overview.md @@ -52,13 +52,13 @@ Bitmap effects enable designers and developers to apply visual effects to render ## Creating Custom Effects - [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] also provides unmanaged interfaces to create custom effects that can be used in managed [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] applications. For additional reference material for creating custom bitmap effects, see the [Unmanaged WPF Bitmap Effect](https://msdn.microsoft.com/library/ms735092.aspx) documentation. + [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] also provides unmanaged interfaces to create custom effects that can be used in managed [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] applications. For additional reference material for creating custom bitmap effects, see the [Unmanaged WPF Bitmap Effect](https://docs.microsoft.com/previous-versions/windows/desktop/wibe/-wibe-lh) documentation. ## See Also - [Unmanaged WPF Bitmap Effect](https://msdn.microsoft.com/library/ms735092.aspx) + [Unmanaged WPF Bitmap Effect](https://docs.microsoft.com/previous-versions/windows/desktop/wibe/-wibe-lh) [Imaging Overview](../../../../docs/framework/wpf/graphics-multimedia/imaging-overview.md) [Security](../../../../docs/framework/wpf/security-wpf.md) [WPF Graphics Rendering Overview](../../../../docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md) diff --git a/docs/framework/wpf/graphics-multimedia/extend-glass-frame-into-a-wpf-application.md b/docs/framework/wpf/graphics-multimedia/extend-glass-frame-into-a-wpf-application.md index d489451f7ace4..17ced344a44c4 100644 --- a/docs/framework/wpf/graphics-multimedia/extend-glass-frame-into-a-wpf-application.md +++ b/docs/framework/wpf/graphics-multimedia/extend-glass-frame-into-a-wpf-application.md @@ -56,10 +56,10 @@ public static extern int DwmExtendFrameIntoClientArea( End Function ``` - [DwmExtendFrameIntoClientArea](https://msdn.microsoft.com/library/aa969512.aspx) is the DWM function that extends the frame into the client area. It takes two parameters; a window handle and a [MARGINS](https://msdn.microsoft.com/library/bb773244.aspx) structure. [MARGINS](https://msdn.microsoft.com/library/bb773244.aspx) is used to tell the DWM how much extra the frame should be extended into the client area. + [DwmExtendFrameIntoClientArea](/windows/desktop/api/dwmapi/nf-dwmapi-dwmextendframeintoclientarea) is the DWM function that extends the frame into the client area. It takes two parameters; a window handle and a [MARGINS](/windows/desktop/api/uxtheme/ns-uxtheme-_margins) structure. [MARGINS](/windows/desktop/api/uxtheme/ns-uxtheme-_margins) is used to tell the DWM how much extra the frame should be extended into the client area. ## Example - To use the [DwmExtendFrameIntoClientArea](https://msdn.microsoft.com/library/aa969512.aspx) function, a window handle must be obtained. In [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], the window handle can be obtained from the property of an . In the following example, the frame is extended into the client area on the event of the window. + To use the [DwmExtendFrameIntoClientArea](/windows/desktop/api/dwmapi/nf-dwmapi-dwmextendframeintoclientarea) function, a window handle must be obtained. In [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], the window handle can be obtained from the property of an . In the following example, the frame is extended into the client area on the event of the window. ```csharp void OnLoaded(object sender, RoutedEventArgs e) @@ -144,6 +144,6 @@ void OnLoaded(object sender, RoutedEventArgs e) ![Glass Frame Extended into a WPF application.](../../../../docs/framework/wpf/graphics-multimedia/media/wpfextendedglassintoclient.PNG "WPFextendedGlassIntoClient") ## See Also - [Desktop Window Manager Overview](https://msdn.microsoft.com/library/aa969540.aspx) - [Desktop Window Manager Blur Overview](https://msdn.microsoft.com/library/aa969537.aspx) - [DwmExtendFrameIntoClientArea](https://msdn.microsoft.com/library/aa969512.aspx) + [Desktop Window Manager Overview](/windows/desktop/dwm/dwm-overview) + [Desktop Window Manager Blur Overview](/windows/desktop/dwm/blur-ovw) + [DwmExtendFrameIntoClientArea](/windows/desktop/api/dwmapi/nf-dwmapi-dwmextendframeintoclientarea) diff --git a/docs/framework/wpf/graphics-multimedia/imaging-overview.md b/docs/framework/wpf/graphics-multimedia/imaging-overview.md index cceb139dbeec0..49a9bf49f2342 100644 --- a/docs/framework/wpf/graphics-multimedia/imaging-overview.md +++ b/docs/framework/wpf/graphics-multimedia/imaging-overview.md @@ -48,7 +48,7 @@ This topic provides an introduction to the [!INCLUDE[TLA#tla_wic](../../../../in The majority of the managed [!INCLUDE[TLA2#tla_wic](../../../../includes/tla2sharptla-wic-md.md)] [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] reside in the namespace, though several important types, such as and reside in the namespace and resides in the namespace. - This topic provides additional information about the managed component. For more information on the unmanaged [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] see the [Unmanaged WPF Imaging Component](https://msdn.microsoft.com/library/ee719902.aspx) documentation. + This topic provides additional information about the managed component. For more information on the unmanaged [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] see the [Unmanaged WPF Imaging Component](/windows/desktop/wic/-wic-lh) documentation. ## WPF Image Formats diff --git a/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md b/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md index 49cc2bbc1eca0..99634e7ce3e6b 100644 --- a/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md +++ b/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md @@ -199,7 +199,7 @@ Diagram of Win32 rendering sequence Diagram of WPF rendering sequence #### Intelligent Redrawing - One of the biggest benefits in using retained mode graphics is that [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] can efficiently optimize what needs to be redrawn in the application. Even if you have a complex scene with varying levels of opacity, you generally do not need to write special-purpose code to optimize redrawing. Compare this with Win32 programming in which you can spend a great deal of effort in optimizing your application by minimizing the amount of redrawing in the update region. See [Redrawing in the Update Region](https://msdn.microsoft.com/library/dd162909.aspx) for an example of the type of complexity involved in optimizing redrawing in Win32 applications. + One of the biggest benefits in using retained mode graphics is that [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] can efficiently optimize what needs to be redrawn in the application. Even if you have a complex scene with varying levels of opacity, you generally do not need to write special-purpose code to optimize redrawing. Compare this with Win32 programming in which you can spend a great deal of effort in optimizing your application by minimizing the amount of redrawing in the update region. See [Redrawing in the Update Region](/windows/desktop/gdi/redrawing-in-the-update-region) for an example of the type of complexity involved in optimizing redrawing in Win32 applications. ### Vector Graphics [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] uses **vector graphics** as its rendering data format. Vector graphics—which include Scalable Vector Graphics (SVG), Windows metafiles (.wmf), and TrueType fonts—store rendering data and transmit it as a list of instructions that describe how to recreate an image using graphics primitives. For example, TrueType fonts are outline fonts that describe a set of lines, curves, and commands, rather than an array of pixels. One of the key benefits of vector graphics is the ability to scale to any size and resolution. diff --git a/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md b/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md index b06cbfd51506d..ec7b65ede6b42 100644 --- a/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md +++ b/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md @@ -141,7 +141,7 @@ Change Targets dialog box in Visual Studio 2012 ➌ Requires [Microsoft HTTP Client Libraries](https://www.nuget.org/packages/Microsoft.Net.Http) package > [!WARNING] -> You may encounter errors when you reference the [Microsoft Compression](https://www.nuget.org/packages/Microsoft.Bcl.Compression) and [Microsoft HTTP Client Libraries](https://www.nuget.org/packages/Microsoft.Net.Http) packages from a portable library used by a Windows Phone Silverlight 8.1 app. For more information, see [Platform compatibility and breaking changes for Windows Phone Silverlight 8.1 apps](/previous-versions/windows/apps/dn642084(v=vs.105)). +> You may encounter errors when you reference the [Microsoft Compression](https://www.nuget.org/packages/Microsoft.Bcl.Compression) and [Microsoft HTTP Client Libraries](https://www.nuget.org/packages/Microsoft.Net.Http) packages from a portable library used by a Windows Phone Silverlight 8.1 app. For more information, see [Platform compatibility and breaking changes for Windows Phone Silverlight 8.1 apps](https://docs.microsoft.com/previous-versions/windows/apps/dn642084(v=vs.105)). ## Supported types and members diff --git a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md b/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md index 22b53095ae28a..73b87462589a0 100644 --- a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md +++ b/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md @@ -15,7 +15,7 @@ ms.author: "mairaw" # .NET Framework Support for Windows Store Apps and Windows Runtime The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] supports a number of software development scenarios with the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. These scenarios fall into three categories: -- Developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps with XAML controls, as described in [Roadmap for Windows Store apps using C# or Visual Basic](/previous-versions/windows/apps/br229583(v=win.10)), [How tos (XAML)](/previous-versions/windows/apps/br229566(v=win.10)), and [.NET for Windows Store apps overview](https://msdn.microsoft.com/library/windows/apps/br230302%28v=VS.110%29.aspx). +- Developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps with XAML controls, as described in [Roadmap for Windows Store apps using C# or Visual Basic](https://docs.microsoft.com/previous-versions/windows/apps/br229583(v=win.10)), [How tos (XAML)](https://docs.microsoft.com/previous-versions/windows/apps/br229566(v=win.10)), and [.NET for Windows Store apps overview](https://msdn.microsoft.com/library/windows/apps/br230302%28v=VS.110%29.aspx). - Developing class libraries to use in the [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps that you create with the .NET Framework. @@ -141,8 +141,8 @@ The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] supports a number of so |Title|Description| |-----------|-----------------| |[.NET for Windows Store apps overview](https://msdn.microsoft.com/library/windows/apps/br230302(v=VS.110).aspx)|Describes the .NET Framework types and members that you can use to create [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps and [!INCLUDE[wrt](../../../includes/wrt-md.md)]Components. (In the Windows Dev Center.)| -|[Roadmap for Windows Store apps using C# or Visual Basic](/previous-versions/windows/apps/br229583(v=win.10))|Provides key resources to help you get started developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps by using C# or Visual Basic, including many Quickstart topics, guidelines, and best practices. (In the Windows Dev Center.)| -|[How tos (XAML)](/previous-versions/windows/apps/br229566(v=win.10))|Provides key resources to help you get started developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps by using C# or Visual Basic, including many Quickstart topics, guidelines, and best practices. (In the Windows Dev Center.)| +|[Roadmap for Windows Store apps using C# or Visual Basic](https://docs.microsoft.com/previous-versions/windows/apps/br229583(v=win.10))|Provides key resources to help you get started developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps by using C# or Visual Basic, including many Quickstart topics, guidelines, and best practices. (In the Windows Dev Center.)| +|[How tos (XAML)](https://docs.microsoft.com/previous-versions/windows/apps/br229566(v=win.10))|Provides key resources to help you get started developing [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps by using C# or Visual Basic, including many Quickstart topics, guidelines, and best practices. (In the Windows Dev Center.)| |[Creating Windows Runtime Components in C# and Visual Basic](https://msdn.microsoft.com/library/windows/apps/br230301%28v=VS.110%29.aspx)|Describes how to create a [!INCLUDE[wrt](../../../includes/wrt-md.md)] component using the .NET Framework, explains how to use it as part of a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app built for Windows using JavaScript, and describes how to debug the combination with Visual Studio. (In the Windows Dev Center.)| |[Windows Runtime reference](/uwp/api/)|The reference documentation for the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. (In the Windows Dev Center.)| |[Passing a URI to the Windows Runtime](../../../docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md)|Describes an issue that can arise when you pass a URI from managed code to the [!INCLUDE[wrt](../../../includes/wrt-md.md)], and how to avoid it.| diff --git a/docs/standard/events/index.md b/docs/standard/events/index.md index 8907f0154f6bd..7f521ce53a8b2 100644 --- a/docs/standard/events/index.md +++ b/docs/standard/events/index.md @@ -16,7 +16,7 @@ ms.author: "ronpet" # Handling and Raising Events Events in the .NET Framework are based on the delegate model. The delegate model follows the observer design pattern, which enables a subscriber to register with, and receive notifications from, a provider. An event sender pushes a notification that an event has happened, and an event receiver receives that notification and defines a response to it. This article describes the major components of the delegate model, how to consume events in applications, and how to implement events in your code. - For information about handling events in Windows 8.x Store apps, see [Events and routed events overview](/previous-versions/windows/apps/hh758286(v=win.10)). + For information about handling events in Windows 8.x Store apps, see [Events and routed events overview](https://docs.microsoft.com/previous-versions/windows/apps/hh758286(v=win.10)). ## Events An event is a message sent by an object to signal the occurrence of an action. The action could be caused by user interaction, such as a button click, or it could be raised by some other program logic, such as changing a property’s value. The object that raises the event is called the *event sender*. The event sender doesn't know which object or method will receive (handle) the events it raises. The event is typically a member of the event sender; for example, the event is a member of the class, and the event is a member of the class that implements the interface. diff --git a/docs/standard/io/file-path-formats.md b/docs/standard/io/file-path-formats.md index fe0c9b48de24d..ecdbe4c954a19 100644 --- a/docs/standard/io/file-path-formats.md +++ b/docs/standard/io/file-path-formats.md @@ -175,7 +175,7 @@ Along with the runs of separators and relative segments removed earlier, some ad ## Skipping normalization -Normally, any path passed to a Windows API is (effectively) passed to the [GetFullPathName function](https://msdn.microsoft.com/library/windows/desktop/aa364963(v=vs.85).aspx) and normalized. There is one important exception: a device path that begins with a question mark instead of a period. Unless the path starts exactly with `\\?\` (note the use of the canonical backslash), it is normalized. +Normally, any path passed to a Windows API is (effectively) passed to the [GetFullPathName function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea) and normalized. There is one important exception: a device path that begins with a question mark instead of a period. Unless the path starts exactly with `\\?\` (note the use of the canonical backslash), it is normalized. Why would you want to skip normalization? There are three major reasons: @@ -190,9 +190,9 @@ Why would you want to skip normalization? There are three major reasons: Skipping normalization and max path checks is the only difference between the two device path syntaxes; they are otherwise identical. Be careful with skipping normalization, since you can easily create paths that are difficult for "normal" applications to deal with. -Paths that start with `\\?\` are still normalized if you explicitly pass them to the [GetFullPathName function](https://msdn.microsoft.com/library/windows/desktop/aa364963(v=vs.85).aspx). +Paths that start with `\\?\` are still normalized if you explicitly pass them to the [GetFullPathName function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea). -Note that you can paths of more than `MAX_PATH` characters to [GetFullPathName](https://msdn.microsoft.com/library/windows/desktop/aa364963(v=vs.85).aspx) without `\\?\`. It supports arbitrary length paths up to the maximum string size that Windows can handle. +Note that you can paths of more than `MAX_PATH` characters to [GetFullPathName](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea) without `\\?\`. It supports arbitrary length paths up to the maximum string size that Windows can handle. ## Case and the Windows file system diff --git a/docs/standard/io/how-to-read-text-from-a-file.md b/docs/standard/io/how-to-read-text-from-a-file.md index 442eee3f38f00..faa65fcf38cc2 100644 --- a/docs/standard/io/how-to-read-text-from-a-file.md +++ b/docs/standard/io/how-to-read-text-from-a-file.md @@ -18,7 +18,7 @@ ms.author: "mairaw" # How to: Read Text from a File The following examples show how to read text synchronously and asynchronously from a text file using .NET for desktop apps. In both examples, when you create the instance of the class, you provide the relative or absolute path to the file. The following examples assume that the file named TestFile.txt is in the same folder as the application. - These code examples do not apply to developing for Windows Store Apps because the Windows Runtime provides different stream types for reading and writing to files. For an example that shows how to read text from a file in a Windows Store app, see [Quickstart: Reading and writing files](https://docs.microsoft.com/en-us/previous-versions/windows/apps/hh758325(v=win.10)). For examples that show how to convert between .NET Framework streams and Windows runtime streams, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](../../../docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md). + These code examples do not apply to developing for Windows Store Apps because the Windows Runtime provides different stream types for reading and writing to files. For an example that shows how to read text from a file in a Windows Store app, see [Quickstart: Reading and writing files](https://docs.microsoft.com/previous-versions/windows/apps/hh758325(v=win.10)). For examples that show how to convert between .NET Framework streams and Windows runtime streams, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](../../../docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md). ## Example The following example shows a synchronous read operation within a console application. In this example, the text file is opened using a stream reader, the contents are copied to a string, and the string is output to the console. diff --git a/docs/standard/io/index.md b/docs/standard/io/index.md index 8bda9afd4c3d6..db1416e9d0130 100644 --- a/docs/standard/io/index.md +++ b/docs/standard/io/index.md @@ -114,7 +114,7 @@ For path naming conventions and the ways to express a file path for Windows syst ## Isolated Storage Isolated storage is a data storage mechanism that provides isolation and safety by defining standardized ways of associating code with saved data. The storage provides a virtual file system that is isolated by user, assembly, and (optionally) domain. Isolated storage is particularly useful when your application does not have permission to access user files. You can save settings or files for your application in a manner that is controlled by the computer's security policy. - Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps; instead, use application data classes in the [Windows.Storage](/uwp/api/Windows.Storage) namespace. For more information, see [Application data](/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. + Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps; instead, use application data classes in the [Windows.Storage](/uwp/api/Windows.Storage) namespace. For more information, see [Application data](https://docs.microsoft.com/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. The following classes are frequently used when implementing isolated storage: @@ -133,7 +133,7 @@ For path naming conventions and the ways to express a file path for Windows syst - Types specifically related to file operations, such as , , and , are not included in the [!INCLUDE[net_win8_profile](../../../includes/net-win8-profile-md.md)]. Instead, use the types in the [Windows.Storage](http://msdn.microsoft.com/library/windows/apps/windows.storage.aspx) namespace of the [!INCLUDE[wrt](../../../includes/wrt-md.md)], such as [StorageFile](http://msdn.microsoft.com/library/windows/apps/windows.storage.storagefile.aspx) and [StorageFolder](http://msdn.microsoft.com/library/windows/apps/windows.storage.storagefolder.aspx). -- Isolated storage is not available; instead, use [application data](/previous-versions/windows/apps/hh464917(v=win.10)). +- Isolated storage is not available; instead, use [application data](https://docs.microsoft.com/previous-versions/windows/apps/hh464917(v=win.10)). - Use asynchronous methods, such as and , to prevent blocking the UI thread. @@ -141,12 +141,12 @@ For path naming conventions and the ways to express a file path for Windows syst You can convert between .NET Framework streams and Windows Runtime streams, if necessary. For more information, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](../../../docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md) or [System.IO.WindowsRuntimeStreamExtensions](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.aspx). - For more information about I/O operations in a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app, see [Quickstart: Reading and writing files](/previous-versions/windows/apps/hh758325(v=win.10)). + For more information about I/O operations in a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app, see [Quickstart: Reading and writing files](https://docs.microsoft.com/previous-versions/windows/apps/hh758325(v=win.10)). ## I/O and Security When you use the classes in the namespace, you must follow operating system security requirements such as access control lists (ACLs) to control access to files and directories. This requirement is in addition to any requirements. You can manage ACLs programmatically. For more information, see [How to: Add or Remove Access Control List Entries](../../../docs/standard/io/how-to-add-or-remove-access-control-list-entries.md). - Default security policies prevent Internet or intranet applications from accessing files on the user’s computer. Therefore, do not use the I/O classes that require a path to a physical file when writing code that will be downloaded over the Internet or intranet. Instead, use [isolated storage](../../../docs/standard/io/isolated-storage.md) for traditional .NET Framework applications, or use [application data](/previous-versions/windows/apps/hh464917(v=win.10)) for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. + Default security policies prevent Internet or intranet applications from accessing files on the user’s computer. Therefore, do not use the I/O classes that require a path to a physical file when writing code that will be downloaded over the Internet or intranet. Instead, use [isolated storage](../../../docs/standard/io/isolated-storage.md) for traditional .NET Framework applications, or use [application data](https://docs.microsoft.com/previous-versions/windows/apps/hh464917(v=win.10)) for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. A security check is performed only when the stream is constructed. Therefore, do not open a stream and then pass it to less-trusted code or application domains. diff --git a/docs/standard/io/isolated-storage.md b/docs/standard/io/isolated-storage.md index 7f3a755ef9ebb..40563fa131317 100644 --- a/docs/standard/io/isolated-storage.md +++ b/docs/standard/io/isolated-storage.md @@ -25,7 +25,7 @@ ms.author: "mairaw" For [!INCLUDE[desktop_appname](../../../includes/desktop-appname-md.md)] apps, isolated storage is a data storage mechanism that provides isolation and safety by defining standardized ways of associating code with saved data. Standardization provides other benefits as well. Administrators can use tools designed to manipulate isolated storage to configure file storage space, set security policies, and delete unused data. With isolated storage, your code no longer needs unique paths to specify safe locations in the file system, and data is protected from other applications that only have isolated storage access. Hard-coded information that indicates where an application's storage area is located is unnecessary. > [!IMPORTANT] -> Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] API to store local data and files. For more information, see [Application data](/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. +> Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] API to store local data and files. For more information, see [Application data](https://docs.microsoft.com/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. This topic contains the following sections: diff --git a/docs/standard/io/types-of-isolation.md b/docs/standard/io/types-of-isolation.md index b65b1fa9f0433..f1eee9fb0e0a6 100644 --- a/docs/standard/io/types-of-isolation.md +++ b/docs/standard/io/types-of-isolation.md @@ -48,7 +48,7 @@ Types of isolated storage Note that except for roaming stores, isolated storage is always implicitly isolated by computer because it uses the storage facilities that are local to a given computer. > [!IMPORTANT] -> Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] API to store local data and files. For more information, see [Application data](/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. +> Isolated storage is not available for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] API to store local data and files. For more information, see [Application data](https://docs.microsoft.com/previous-versions/windows/apps/hh464917(v=win.10)) in the Windows Dev Center. ## Isolation by User and Assembly diff --git a/docs/standard/security/vulnerabilities-cbc-mode.md b/docs/standard/security/vulnerabilities-cbc-mode.md index 9a9e6d3e06dc5..5bb222786df33 100644 --- a/docs/standard/security/vulnerabilities-cbc-mode.md +++ b/docs/standard/security/vulnerabilities-cbc-mode.md @@ -97,14 +97,14 @@ Applications that are unable to change their messaging format but perform unauth For programs built against the Windows Cryptography: Next Generation (CNG) library: -- The decryption call is to [BCryptDecrypt](https://msdn.microsoft.com/library/windows/desktop/aa375391.aspx), specifying the `BCRYPT_BLOCK_PADDING` flag. -- The key handle has been initialized by calling [BCryptSetProperty](https://msdn.microsoft.com/library/windows/desktop/aa375504.aspx) with [BCRYPT_CHAINING_MODE](https://msdn.microsoft.com/library/windows/desktop/aa376211.aspx#BCRYPT_CHAINING_MODE) set to `BCRYPT_CHAIN_MODE_CBC`. +- The decryption call is to [BCryptDecrypt](/windows/desktop/api/bcrypt/nf-bcrypt-bcryptdecrypt), specifying the `BCRYPT_BLOCK_PADDING` flag. +- The key handle has been initialized by calling [BCryptSetProperty](/windows/desktop/api/bcrypt/nf-bcrypt-bcryptsetproperty) with [BCRYPT_CHAINING_MODE](https://msdn.microsoft.com/library/windows/desktop/aa376211.aspx#BCRYPT_CHAINING_MODE) set to `BCRYPT_CHAIN_MODE_CBC`. - Since `BCRYPT_CHAIN_MODE_CBC` is the default, affected code may not have assigned any value for `BCRYPT_CHAINING_MODE`. For programs built against the older Windows Cryptographic API: -- The decryption call is to [CryptDecrypt](https://msdn.microsoft.com/library/windows/desktop/aa379913.aspx) with `Final=TRUE`. -- The key handle has been initialized by calling [CryptSetKeyParam](https://msdn.microsoft.com/library/windows/desktop/aa380272.aspx) with [KP_MODE](https://msdn.microsoft.com/library/windows/desktop/aa379949.aspx#KP_MODE) set to `CRYPT_MODE_CBC`. +- The decryption call is to [CryptDecrypt](/windows/desktop/api/wincrypt/nf-wincrypt-cryptdecrypt) with `Final=TRUE`. +- The key handle has been initialized by calling [CryptSetKeyParam](/windows/desktop/api/wincrypt/nf-wincrypt-cryptsetkeyparam) with [KP_MODE](https://msdn.microsoft.com/library/windows/desktop/aa379949.aspx#KP_MODE) set to `CRYPT_MODE_CBC`. - Since `CRYPT_MODE_CBC` is the default, affected code may not have assigned any value for `KP_MODE`. ## Finding vulnerable code - managed applications @@ -137,7 +137,7 @@ While stream ciphers aren't susceptible to this particular vulnerability, Micros For managed applications, a CMS EnvelopedData blob can be detected as any value that is passed to . -For native applications, a CMS EnvelopedData blob can be detected as any value provided to a CMS handle via [CryptMsgUpdate](https://msdn.microsoft.com/library/windows/desktop/aa380231.aspx) whose resulting [CMSG_TYPE_PARAM](https://msdn.microsoft.com/library/windows/desktop/aa380227.aspx) is `CMSG_ENVELOPED` and/or the CMS handle is later sent a `CMSG_CTRL_DECRYPT` instruction via [CryptMsgControl](https://msdn.microsoft.com/library/windows/desktop/aa380220.aspx). +For native applications, a CMS EnvelopedData blob can be detected as any value provided to a CMS handle via [CryptMsgUpdate](/windows/desktop/api/wincrypt/nf-wincrypt-cryptmsgupdate) whose resulting [CMSG_TYPE_PARAM](/windows/desktop/api/wincrypt/nf-wincrypt-cryptmsggetparam) is `CMSG_ENVELOPED` and/or the CMS handle is later sent a `CMSG_CTRL_DECRYPT` instruction via [CryptMsgControl](/windows/desktop/api/wincrypt/nf-wincrypt-cryptmsgcontrol). ## Vulnerable code example - managed diff --git a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md index b3459f16ff3a1..4c37f25b5b3a6 100644 --- a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md +++ b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md @@ -11,7 +11,7 @@ author: "rpetrusha" ms.author: "ronpet" --- # Managed and Unmanaged Threading in Windows -Management of all threads is done through the class, including threads created by the common language runtime and those created outside the runtime that enter the managed environment to execute code. The runtime monitors all the threads in its process that have ever executed code within the managed execution environment. It does not track any other threads. Threads can enter the managed execution environment through COM interop (because the runtime exposes managed objects as COM objects to the unmanaged world), the COM [DllGetClassObject](https://msdn.microsoft.com/library/ms680760.aspx) function, and platform invoke. +Management of all threads is done through the class, including threads created by the common language runtime and those created outside the runtime that enter the managed environment to execute code. The runtime monitors all the threads in its process that have ever executed code within the managed execution environment. It does not track any other threads. Threads can enter the managed execution environment through COM interop (because the runtime exposes managed objects as COM objects to the unmanaged world), the COM [DllGetClassObject](/windows/desktop/api/combaseapi/nf-combaseapi-dllgetclassobject) function, and platform invoke. When an unmanaged thread enters the runtime through, for example, a COM callable wrapper, the system checks the thread-local store of that thread to look for an internal managed object. If one is found, the runtime is already aware of this thread. If it cannot find one, however, the runtime builds a new object and installs it in the thread-local store of that thread. @@ -39,7 +39,7 @@ Management of all threads is done through the cla |Close to **CoInitializeEx** (OLE32.DLL)|| ## Managed Threads and COM Apartments - A managed thread can be marked to indicate that it will host a [single-threaded](https://msdn.microsoft.com/library/windows/desktop/ms680112.aspx) or [multithreaded](https://msdn.microsoft.com/library/windows/desktop/ms693421.aspx) apartment. (For more information on the COM threading architecture, see [Processes, threads, and Apartments](https://msdn.microsoft.com/library/windows/desktop/ms693344.aspx).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . + A managed thread can be marked to indicate that it will host a [single-threaded](/windows/desktop/com/single-threaded-apartments) or [multithreaded](/windows/desktop/com/multithreaded-apartments) apartment. (For more information on the COM threading architecture, see [Processes, threads, and Apartments](https://msdn.microsoft.com/library/windows/desktop/ms693344.aspx).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . The property can be set only when the thread is in the state; it can be set only once for a thread. diff --git a/docs/standard/threading/pausing-and-resuming-threads.md b/docs/standard/threading/pausing-and-resuming-threads.md index fbab64be31e1c..de8729a12c9ad 100644 --- a/docs/standard/threading/pausing-and-resuming-threads.md +++ b/docs/standard/threading/pausing-and-resuming-threads.md @@ -37,7 +37,7 @@ The most common ways to synchronize the activities of threads are to block and r > [!NOTE] > If the target thread is not blocked when is called, the thread is not interrupted until it blocks. If the thread never blocks, it could complete without ever being interrupted. - If a wait is a managed wait, then and both wake the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](https://msdn.microsoft.com/library/windows/desktop/ms687032\(v=vs.85\).aspx) function), neither nor can take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: + If a wait is a managed wait, then and both wake the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](/windows/desktop/api/synchapi/nf-synchapi-waitforsingleobject) function), neither nor can take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: - wakes a thread out of any wait it might be in and causes a to be thrown in the destination thread. From b552544a41e869b9abce636b772667272d909a77 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 10 Aug 2018 17:56:57 -0700 Subject: [PATCH 12/13] markdig changes - core and standard folders (#6766) * markdig changes * change link * fix code formatting * feedback #1 * feedback #2 * fix c# code formatting * more code formatting fixes --- docs/core/whats-new/dotnet-core-2-1.md | 4 +- .../samples/usage-of-standard-endpoints.md | 316 ++--- .../custom-date-and-time-format-strings.md | 1247 +++++++++-------- .../custom-timespan-format-strings.md | 746 +++++----- .../base-types/enumeration-format-strings.md | 60 +- ...mextensions-asrandomaccessstream-method.md | 108 +- docs/standard/data/xml/extending-the-dom.md | 474 +++---- ...ary-behaviors-in-the-xsltransform-class.md | 145 +- ...result-tree-fragment-in-transformations.md | 366 ++--- ...sheet-directives-embedded-in-a-document.md | 52 +- ...xdr-validation-with-xmlschemacollection.md | 289 ++-- ...sformations-with-the-xsltransform-class.md | 174 +-- .../garbage-collection/large-object-heap.md | 90 +- ...etween-dotnet-streams-and-winrt-streams.md | 136 +- .../docker-defined.md | 2 +- .../client-side-validation.md | 19 +- ...that-control-encoded-soap-serialization.md | 50 +- ...ling-xml-serialization-using-attributes.md | 592 ++++---- ...ify-xml-element-and-xml-attribute-names.md | 323 ++--- .../introducing-xml-serialization.md | 324 ++--- .../xml-and-soap-serialization.md | 148 +- 21 files changed, 2861 insertions(+), 2804 deletions(-) diff --git a/docs/core/whats-new/dotnet-core-2-1.md b/docs/core/whats-new/dotnet-core-2-1.md index 87c53bbc89a10..9364608b40812 100644 --- a/docs/core/whats-new/dotnet-core-2-1.md +++ b/docs/core/whats-new/dotnet-core-2-1.md @@ -117,7 +117,7 @@ Using the .NET Core 2.0 SDK, self-contained applications are published with the ## Windows Compatibility Pack -When you port existing code from the .NET Framework to .NET Core, you can use the [Windows Compatibility Pack](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). It provides access to 20,000 more APIs than are available in .NET Core. These APIs include types in the namespace, the class, WMI, Performance Counters, Windows Services, and the Windows registry types and members. +When you port existing code from the .NET Framework to .NET Core, you can use the [Windows Compatibility Pack](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). It provides access to 20,000 more APIs than are available in .NET Core. These APIs include types in the namespace, the class, WMI, Performance Counters, Windows Services, and the Windows registry types and members. ## JIT compiler improvements @@ -189,7 +189,7 @@ The behavior is the same as is a memory-clearing routine that cannot be optimized. -- The static method fills a with random values. +- The static method fills a with random values. - The is now supported on Linux and maxOS. diff --git a/docs/framework/wcf/samples/usage-of-standard-endpoints.md b/docs/framework/wcf/samples/usage-of-standard-endpoints.md index f8919d1af2d7e..703ea3786a3b4 100644 --- a/docs/framework/wcf/samples/usage-of-standard-endpoints.md +++ b/docs/framework/wcf/samples/usage-of-standard-endpoints.md @@ -4,163 +4,163 @@ ms.date: "03/30/2017" ms.assetid: ecd6a62f-9619-4778-a497-6f888087a9ea --- # Usage of Standard Endpoints -This sample demonstrates how to use standard endpoints in service configuration files. A standard endpoint allows the user to simplify endpoint definitions by using a single property to describe an address, binding and contract combination with additional properties associated to it. This sample demonstrates how to define and implement a custom standard endpoint and how to define specific properties in the endpoint. - -## Sample Details - Service endpoints can be specified by supplying three parameters: address, binding and contract. Other parameters that can be supplied include behavior configuration, headers, listen URI, and so on. In some cases, any or all of addresses, bindings and contracts have values that cannot change. For this reason, it is possible to use standard endpoints. Some examples of such endpoints include metadata exchange endpoints and discovery endpoints. Standard endpoints also improve usability by allowing configuration of service endpoints without having to provide information of a fixed nature or to create their own standard endpoints, for example to improve usability by supplying a reasonable set of default values and thus reducing the verbosity of configuration files. - - This sample consists of two projects: the service that defines two standard endpoints and the client that communicates with the service. The way the standard endpoints are defined for the service in the configuration file is show in the following example. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - - The first endpoint defined for the service is of kind `customEndpoint`, whose definition can be seen in the `` section, in which the property `property` is given the value `true`. This is the case of an endpoint customized with a new property. The second endpoint corresponds to a metadata endpoint, in which the values for address, binding and contract are fixed. - - To define the standard endpoint element, a class that derives from `StandardEndpointElement` must be created. In the case of this sample, the `CustomEndpointElement` class has been defined as shown in the following example. - -```csharp -public class CustomEndpointElement : StandardEndpointElement -{ - public bool Property - { - get { return (bool)base["property"]; } - set { base["property"] = value; } - } - - protected override ConfigurationPropertyCollection Properties - { - get - { - ConfigurationPropertyCollection properties = base.Properties; - properties.Add(new ConfigurationProperty("property", typeof(bool), false, ConfigurationPropertyOptions.None)); - return properties; - } - } - - protected override Type EndpointType - { - get { return typeof(CustomEndpoint); } - } - - protected override ServiceEndpoint CreateServiceEndpoint(ContractDescription contract) - { - return new CustomEndpoint(); - } - - protected override void OnApplyConfiguration(ServiceEndpoint endpoint, ServiceEndpointElement serviceEndpointElement) - { - CustomEndpoint customEndpoint = (CustomEndpoint)endpoint; - customEndpoint.Property = this.Property; - } - - protected override void OnApplyConfiguration(ServiceEndpoint endpoint, ChannelEndpointElement channelEndpointElement) - { - CustomEndpoint customEndpoint = (CustomEndpoint)endpoint; - customEndpoint.Property = this.Property; - } - - protected override void OnInitializeAndValidate(ServiceEndpointElement serviceEndpointElement) - { - } - - protected override void OnInitializeAndValidate(ChannelEndpointElement channelEndpointElement) - { - } -} -``` - - In the `CreateServiceEndpoint` function, a `CustomEndpoint` object is created. Its definition is shown in the following example. - -``` -public class CustomEndpoint : ServiceEndpoint - { - public CustomEndpoint() - : this(string.Empty) - { - } - - public CustomEndpoint(string address) - : this(address, ContractDescription.GetContract(typeof(ICalculator))) - { - } - - public CustomEndpoint(string address, ContractDescription contract) - : base(contract) - { - this.Binding = new BasicHttpBinding(); - this.IsSystemEndpoint = false; - } - - public bool Property - { - get; - set; - } - } -``` - - To perform the communication between service and client, a service reference is created in the client to the service. When the sample is built and executed, the service executes and the client communicates with it. Note that the service reference should be updated every time there is some change in the service. - -#### To use this sample - -1. Using [!INCLUDE[vs_current_long](../../../../includes/vs-current-long-md.md)], open the StandardEndpoints.sln file. - -2. Enable multiple projects to start up. - - 1. In **Solution Explorer**, right-click the Standard Endpoints solution and then select **Properties**. - - 2. In **Common Properties**, select **Startup Project**, and then click **Multiple Startup Projects**. - - 3. Move the Service project to the beginning of the list, with the **Action** set to **Start**. - - 4. Move the Client project after the Service project, also with the **Action** set to **Start**. - - This specifies that the Client project is executed after the Service project. - -3. To run the solution, press F5. - + +This sample demonstrates how to use standard endpoints in service configuration files. A standard endpoint allows the user to simplify endpoint definitions by using a single property to describe an address, binding and contract combination with additional properties associated to it. This sample demonstrates how to define and implement a custom standard endpoint and how to define specific properties in the endpoint. + +## Sample Details + +Service endpoints can be specified by supplying three parameters: address, binding and contract. Other parameters that can be supplied include behavior configuration, headers, listen URI, and so on. In some cases, any or all of addresses, bindings and contracts have values that cannot change. For this reason, it is possible to use standard endpoints. Some examples of such endpoints include metadata exchange endpoints and discovery endpoints. Standard endpoints also improve usability by allowing configuration of service endpoints without having to provide information of a fixed nature or to create their own standard endpoints, for example to improve usability by supplying a reasonable set of default values and thus reducing the verbosity of configuration files. + +This sample consists of two projects: the service that defines two standard endpoints and the client that communicates with the service. The way the standard endpoints are defined for the service in the configuration file is show in the following example. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +The first endpoint defined for the service is of kind `customEndpoint`, whose definition can be seen in the `` section, in which the property `property` is given the value `true`. This is the case of an endpoint customized with a new property. The second endpoint corresponds to a metadata endpoint, in which the values for address, binding and contract are fixed. + +To define the standard endpoint element, a class that derives from `StandardEndpointElement` must be created. In the case of this sample, the `CustomEndpointElement` class has been defined as shown in the following example. + +```csharp +public class CustomEndpointElement : StandardEndpointElement +{ + public bool Property + { + get { return (bool)base["property"]; } + set { base["property"] = value; } + } + + protected override ConfigurationPropertyCollection Properties + { + get + { + ConfigurationPropertyCollection properties = base.Properties; + properties.Add(new ConfigurationProperty("property", typeof(bool), false, ConfigurationPropertyOptions.None)); + return properties; + } + } + + protected override Type EndpointType + { + get { return typeof(CustomEndpoint); } + } + + protected override ServiceEndpoint CreateServiceEndpoint(ContractDescription contract) + { + return new CustomEndpoint(); + } + + protected override void OnApplyConfiguration(ServiceEndpoint endpoint, ServiceEndpointElement serviceEndpointElement) + { + CustomEndpoint customEndpoint = (CustomEndpoint)endpoint; + customEndpoint.Property = this.Property; + } + + protected override void OnApplyConfiguration(ServiceEndpoint endpoint, ChannelEndpointElement channelEndpointElement) + { + CustomEndpoint customEndpoint = (CustomEndpoint)endpoint; + customEndpoint.Property = this.Property; + } + + protected override void OnInitializeAndValidate(ServiceEndpointElement serviceEndpointElement) + { + } + + protected override void OnInitializeAndValidate(ChannelEndpointElement channelEndpointElement) + { + } +} +``` + +In the `CreateServiceEndpoint` function, a `CustomEndpoint` object is created. Its definition is shown in the following example: + +```csharp +public class CustomEndpoint : ServiceEndpoint +{ + public CustomEndpoint() + : this(string.Empty) + { + } + + public CustomEndpoint(string address) + : this(address, ContractDescription.GetContract(typeof(ICalculator))) + { + } + + public CustomEndpoint(string address, ContractDescription contract) + : base(contract) + { + this.Binding = new BasicHttpBinding(); + this.IsSystemEndpoint = false; + } + + public bool Property + { + get; + set; + } +} +``` + + To perform the communication between service and client, a service reference is created in the client to the service. When the sample is built and executed, the service executes and the client communicates with it. Note that the service reference should be updated every time there is some change in the service. + +#### To use this sample + +1. Using [!INCLUDE[vs_current_long](../../../../includes/vs-current-long-md.md)], open the StandardEndpoints.sln file. + +2. Enable multiple projects to start up. + + 1. In **Solution Explorer**, right-click the Standard Endpoints solution and then select **Properties**. + + 2. In **Common Properties**, select **Startup Project**, and then click **Multiple Startup Projects**. + + 3. Move the Service project to the beginning of the list, with the **Action** set to **Start**. + + 4. Move the Client project after the Service project, also with the **Action** set to **Start**. + + This specifies that the Client project is executed after the Service project. + +3. To run the solution, press F5. + > [!NOTE] -> If these steps do not work, then make sure that your environment has been properly set up, using the following steps: -> -> 1. Ensure that you have performed the [One-Time Setup Procedure for the Windows Communication Foundation Samples](../../../../docs/framework/wcf/samples/one-time-setup-procedure-for-the-wcf-samples.md). -> 2. To build the solution, follow the instructions in [Building the Windows Communication Foundation Samples](../../../../docs/framework/wcf/samples/building-the-samples.md). -> 3. To run the sample in a single or multiple computer configurations, follow the instructions in [Running the Windows Communication Foundation Samples](../../../../docs/framework/wcf/samples/running-the-samples.md). - +> If these steps don't work, then make sure that your environment has been properly set up, using the following steps: +> +> 1. Ensure that you have performed the [One-Time Setup Procedure for the Windows Communication Foundation Samples](one-time-setup-procedure-for-the-wcf-samples.md). +> 2. To build the solution, follow the instructions in [Building the Windows Communication Foundation Samples](building-the-samples.md). +> 3. To run the sample in a single or multiple computer configurations, follow the instructions in [Running the Windows Communication Foundation Samples](running-the-samples.md). + > [!IMPORTANT] -> The samples may already be installed on your machine. Check for the following (default) directory before continuing. -> -> `:\WF_WCF_Samples` -> -> If this directory does not exist, go to [Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4](http://go.microsoft.com/fwlink/?LinkId=150780) to download all Windows Communication Foundation (WCF) and [!INCLUDE[wf1](../../../../includes/wf1-md.md)] samples. This sample is located in the following directory. -> -> `:\WF_WCF_Samples\WCF\Basic\Services\StandardEndpoints` - -## See Also +> The samples may already be installed on your machine. Check for the following (default) directory before continuing. +> +> `:\WF_WCF_Samples` +> +> If this directory doesn't exist, go to [Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4](http://go.microsoft.com/fwlink/?LinkId=150780) to download all Windows Communication Foundation (WCF) and [!INCLUDE[wf1](../../../../includes/wf1-md.md)] samples. This sample is located in the following directory. +> +> `:\WF_WCF_Samples\WCF\Basic\Services\StandardEndpoints` diff --git a/docs/standard/base-types/custom-date-and-time-format-strings.md b/docs/standard/base-types/custom-date-and-time-format-strings.md index 69993961e447f..f4072d6223d60 100644 --- a/docs/standard/base-types/custom-date-and-time-format-strings.md +++ b/docs/standard/base-types/custom-date-and-time-format-strings.md @@ -18,678 +18,679 @@ author: "rpetrusha" ms.author: "ronpet" --- # Custom Date and Time Format Strings -A date and time format string defines the text representation of a or value that results from a formatting operation . It can also define the representation of a date and time value that is required in a parsing operation in order to successfully convert the string to a date and time. A custom format string consists of one or more custom date and time format specifiers. Any string that is not a [standard date and time format string](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) is interpreted as a custom date and time format string. - + +A date and time format string defines the text representation of a or value that results from a formatting operation . It can also define the representation of a date and time value that is required in a parsing operation in order to successfully convert the string to a date and time. A custom format string consists of one or more custom date and time format specifiers. Any string that is not a [standard date and time format string](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) is interpreted as a custom date and time format string. + > [!TIP] -> You can download the [Formatting Utility](https://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d), an application that enables you to apply format strings to either date and time or numeric values and displays the result string. +> You can download the [Formatting Utility](https://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d), an application that enables you to apply format strings to either date and time or numeric values and displays the result string. + + Custom date and time format strings can be used with both and values. - Custom date and time format strings can be used with both and values. - [!INCLUDE[C# interactive-note](~/includes/csharp-interactive-with-utc-note.md)] - In formatting operations, custom date and time format strings can be used either with the `ToString` method of a date and time instance or with a method that supports composite formatting. The following example illustrates both uses. - + In formatting operations, custom date and time format strings can be used either with the `ToString` method of a date and time instance or with a method that supports composite formatting. The following example illustrates both uses. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#17](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/custandformatting1.cs#17)] - [!code-vb[Formatting.DateAndTime.Custom#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandformatting1.vb#17)] - - In parsing operations, custom date and time format strings can be used with the , , , and methods. These methods require that an input string conform exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. - + [!code-vb[Formatting.DateAndTime.Custom#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandformatting1.vb#17)] + + In parsing operations, custom date and time format strings can be used with the , , , and methods. These methods require that an input string conform exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#18](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/custandparsing1.cs#18)] - [!code-vb[Formatting.DateAndTime.Custom#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandparsing1.vb#18)] - - The following table describes the custom date and time format specifiers and displays a result string produced by each format specifier. By default, result strings reflect the formatting conventions of the en-US culture. If a particular format specifier produces a localized result string, the example also notes the culture to which the result string applies. See the Notes section for additional information about using custom date and time format strings. - -|Format specifier|Description|Examples| -|----------------------|-----------------|--------------| -|"d"|The day of the month, from 1 through 31.

More information: [The "d" Custom Format Specifier](#dSpecifier).|2009-06-01T13:45:30 -> 1

2009-06-15T13:45:30 -> 15| -|"dd"|The day of the month, from 01 through 31.

More information: [The "dd" Custom Format Specifier](#ddSpecifier).|2009-06-01T13:45:30 -> 01

2009-06-15T13:45:30 -> 15| -|"ddd"|The abbreviated name of the day of the week.

More information: [The "ddd" Custom Format Specifier](#dddSpecifier).|2009-06-15T13:45:30 -> Mon (en-US)

2009-06-15T13:45:30 -> Пн (ru-RU)

2009-06-15T13:45:30 -> lun. (fr-FR)| -|"dddd"|The full name of the day of the week.

More information: [The "dddd" Custom Format Specifier](#ddddSpecifier).|2009-06-15T13:45:30 -> Monday (en-US)

2009-06-15T13:45:30 -> понедельник (ru-RU)

2009-06-15T13:45:30 -> lundi (fr-FR)| -|"f"|The tenths of a second in a date and time value.

More information: [The "f" Custom Format Specifier](#fSpecifier).|2009-06-15T13:45:30.6170000 -> 6

2009-06-15T13:45:30.05 -> 0| -|"ff"|The hundredths of a second in a date and time value.

More information: [The "ff" Custom Format Specifier](#ffSpecifier).|2009-06-15T13:45:30.6170000 -> 61

2009-06-15T13:45:30.0050000 -> 00| -|"fff"|The milliseconds in a date and time value.

More information: [The "fff" Custom Format Specifier](#fffSpecifier).|6/15/2009 13:45:30.617 -> 617

6/15/2009 13:45:30.0005 -> 000| -|"ffff"|The ten thousandths of a second in a date and time value.

More information: [The "ffff" Custom Format Specifier](#ffffSpecifier).|2009-06-15T13:45:30.6175000 -> 6175

2009-06-15T13:45:30.0000500 -> 0000| -|"fffff"|The hundred thousandths of a second in a date and time value.

More information: [The "fffff" Custom Format Specifier](#fffffSpecifier).|2009-06-15T13:45:30.6175400 -> 61754

6/15/2009 13:45:30.000005 -> 00000| -|"ffffff"|The millionths of a second in a date and time value.

More information: [The "ffffff" Custom Format Specifier](#ffffffSpecifier).|2009-06-15T13:45:30.6175420 -> 617542

2009-06-15T13:45:30.0000005 -> 000000| -|"fffffff"|The ten millionths of a second in a date and time value.

More information: [The "fffffff" Custom Format Specifier](#fffffffSpecifier).|2009-06-15T13:45:30.6175425 -> 6175425

2009-06-15T13:45:30.0001150 -> 0001150| -|"F"|If non-zero, the tenths of a second in a date and time value.

More information: [The "F" Custom Format Specifier](#F_Specifier).|2009-06-15T13:45:30.6170000 -> 6

2009-06-15T13:45:30.0500000 -> (no output)| -|"FF"|If non-zero, the hundredths of a second in a date and time value.

More information: [The "FF" Custom Format Specifier](#FF_Specifier).|2009-06-15T13:45:30.6170000 -> 61

2009-06-15T13:45:30.0050000 -> (no output)| -|"FFF"|If non-zero, the milliseconds in a date and time value.

More information: [The "FFF" Custom Format Specifier](#FFF_Specifier).|2009-06-15T13:45:30.6170000 -> 617

2009-06-15T13:45:30.0005000 -> (no output)| -|"FFFF"|If non-zero, the ten thousandths of a second in a date and time value.

More information: [The "FFFF" Custom Format Specifier](#FFFF_Specifier).|2009-06-15T13:45:30.5275000 -> 5275

2009-06-15T13:45:30.0000500 -> (no output)| -|"FFFFF"|If non-zero, the hundred thousandths of a second in a date and time value.

More information: [The "FFFFF" Custom Format Specifier](#FFFFF_Specifier).|2009-06-15T13:45:30.6175400 -> 61754

2009-06-15T13:45:30.0000050 -> (no output)| -|"FFFFFF"|If non-zero, the millionths of a second in a date and time value.

More information: [The "FFFFFF" Custom Format Specifier](#FFFFFF_Specifier).|2009-06-15T13:45:30.6175420 -> 617542

2009-06-15T13:45:30.0000005 -> (no output)| -|"FFFFFFF"|If non-zero, the ten millionths of a second in a date and time value.

More information: [The "FFFFFFF" Custom Format Specifier](#FFFFFFF_Specifier).|2009-06-15T13:45:30.6175425 -> 6175425

2009-06-15T13:45:30.0001150 -> 000115| -|"g", "gg"|The period or era.

More information: [The "g" or "gg" Custom Format Specifier](#gSpecifier).|2009-06-15T13:45:30.6170000 -> A.D.| -|"h"|The hour, using a 12-hour clock from 1 to 12.

More information: [The "h" Custom Format Specifier](#hSpecifier).|2009-06-15T01:45:30 -> 1

2009-06-15T13:45:30 -> 1| -|"hh"|The hour, using a 12-hour clock from 01 to 12.

More information: [The "hh" Custom Format Specifier](#hhSpecifier).|2009-06-15T01:45:30 -> 01

2009-06-15T13:45:30 -> 01| -|"H"|The hour, using a 24-hour clock from 0 to 23.

More information: [The "H" Custom Format Specifier](#H_Specifier).|2009-06-15T01:45:30 -> 1

2009-06-15T13:45:30 -> 13| -|"HH"|The hour, using a 24-hour clock from 00 to 23.

More information: [The "HH" Custom Format Specifier](#HH_Specifier).|2009-06-15T01:45:30 -> 01

2009-06-15T13:45:30 -> 13| -|"K"|Time zone information.

More information: [The "K" Custom Format Specifier](#KSpecifier).|With values:

2009-06-15T13:45:30, Kind Unspecified ->

2009-06-15T13:45:30, Kind Utc -> Z

2009-06-15T13:45:30, Kind Local -> -07:00 (depends on local computer settings)

With values:

2009-06-15T01:45:30-07:00 --> -07:00

2009-06-15T08:45:30+00:00 --> +00:00| -|"m"|The minute, from 0 through 59.

More information: [The "m" Custom Format Specifier](#mSpecifier).|2009-06-15T01:09:30 -> 9

2009-06-15T13:29:30 -> 29| -|"mm"|The minute, from 00 through 59.

More information: [The "mm" Custom Format Specifier](#mmSpecifier).|2009-06-15T01:09:30 -> 09

2009-06-15T01:45:30 -> 45| -|"M"|The month, from 1 through 12.

More information: [The "M" Custom Format Specifier](#M_Specifier).|2009-06-15T13:45:30 -> 6| -|"MM"|The month, from 01 through 12.

More information: [The "MM" Custom Format Specifier](#MM_Specifier).|2009-06-15T13:45:30 -> 06| -|"MMM"|The abbreviated name of the month.

More information: [The "MMM" Custom Format Specifier](#MMM_Specifier).|2009-06-15T13:45:30 -> Jun (en-US)

2009-06-15T13:45:30 -> juin (fr-FR)

2009-06-15T13:45:30 -> Jun (zu-ZA)| -|"MMMM"|The full name of the month.

More information: [The "MMMM" Custom Format Specifier](#MMMM_Specifier).|2009-06-15T13:45:30 -> June (en-US)

2009-06-15T13:45:30 -> juni (da-DK)

2009-06-15T13:45:30 -> uJuni (zu-ZA)| -|"s"|The second, from 0 through 59.

More information: [The "s" Custom Format Specifier](#sSpecifier).|2009-06-15T13:45:09 -> 9| -|"ss"|The second, from 00 through 59.

More information: [The "ss" Custom Format Specifier](#ssSpecifier).|2009-06-15T13:45:09 -> 09| -|"t"|The first character of the AM/PM designator.

More information: [The "t" Custom Format Specifier](#tSpecifier).|2009-06-15T13:45:30 -> P (en-US)

2009-06-15T13:45:30 -> 午 (ja-JP)

2009-06-15T13:45:30 -> (fr-FR)| -|"tt"|The AM/PM designator.

More information: [The "tt" Custom Format Specifier](#ttSpecifier).|2009-06-15T13:45:30 -> PM (en-US)

2009-06-15T13:45:30 -> 午後 (ja-JP)

2009-06-15T13:45:30 -> (fr-FR)| -|"y"|The year, from 0 to 99.

More information: [The "y" Custom Format Specifier](#ySpecifier).|0001-01-01T00:00:00 -> 1

0900-01-01T00:00:00 -> 0

1900-01-01T00:00:00 -> 0

2009-06-15T13:45:30 -> 9

2019-06-15T13:45:30 -> 19| -|"yy"|The year, from 00 to 99.

More information: [The "yy" Custom Format Specifier](#yySpecifier).|0001-01-01T00:00:00 -> 01

0900-01-01T00:00:00 -> 00

1900-01-01T00:00:00 -> 00

2019-06-15T13:45:30 -> 19| -|"yyy"|The year, with a minimum of three digits.

More information: [The "yyy" Custom Format Specifier](#yyySpecifier).|0001-01-01T00:00:00 -> 001

0900-01-01T00:00:00 -> 900

1900-01-01T00:00:00 -> 1900

2009-06-15T13:45:30 -> 2009| -|"yyyy"|The year as a four-digit number.

More information: [The "yyyy" Custom Format Specifier](#yyyySpecifier).|0001-01-01T00:00:00 -> 0001

0900-01-01T00:00:00 -> 0900

1900-01-01T00:00:00 -> 1900

2009-06-15T13:45:30 -> 2009| -|"yyyyy"|The year as a five-digit number.

More information: [The "yyyyy" Custom Format Specifier](#yyyyySpecifier).|0001-01-01T00:00:00 -> 00001

2009-06-15T13:45:30 -> 02009| -|"z"|Hours offset from UTC, with no leading zeros.

More information: [The "z" Custom Format Specifier](#zSpecifier).|2009-06-15T13:45:30-07:00 -> -7| -|"zz"|Hours offset from UTC, with a leading zero for a single-digit value.

More information: [The "zz" Custom Format Specifier](#zzSpecifier).|2009-06-15T13:45:30-07:00 -> -07| -|"zzz"|Hours and minutes offset from UTC.

More information: [The "zzz" Custom Format Specifier](#zzzSpecifier).|2009-06-15T13:45:30-07:00 -> -07:00| -|":"|The time separator.

More information: [The ":" Custom Format Specifier](#timeSeparator).|2009-06-15T13:45:30 -> : (en-US)

2009-06-15T13:45:30 -> . (it-IT)

2009-06-15T13:45:30 -> : (ja-JP)| -|"/"|The date separator.

More Information: [The "/" Custom Format Specifier](#dateSeparator).|2009-06-15T13:45:30 -> / (en-US)

2009-06-15T13:45:30 -> - (ar-DZ)

2009-06-15T13:45:30 -> . (tr-TR)| -|"*string*"

'*string*'|Literal string delimiter.

More information: [Character literals](#Literals).|2009-06-15T13:45:30 ("arr:" h:m t) -> arr: 1:45 P

2009-06-15T13:45:30 ('arr:' h:m t) -> arr: 1:45 P| -|%|Defines the following character as a custom format specifier.

More information:[Using Single Custom Format Specifiers](#UsingSingleSpecifiers).|2009-06-15T13:45:30 (%h) -> 1| -|\\|The escape character.

More information: [Character literals](#Literals) and [Using the Escape Character](#escape).|2009-06-15T13:45:30 (h \h) -> 1 h| -|Any other character|The character is copied to the result string unchanged.

More information: [Character literals](#Literals).|2009-06-15T01:45:30 (arr hh:mm t) -> arr 01:45 A| - - The following sections provide additional information about each custom date and time format specifier. Unless otherwise noted, each specifier produces an identical string representation regardless of whether it is used with a value or a value. - - -## The "d" custom format specifier - The "d" custom format specifier represents the day of the month as a number from 1 through 31. A single-digit day is formatted without a leading zero. - - If the "d" format specifier is used without other custom format specifiers, it is interpreted as the "d" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "d" custom format specifier in several format strings. - + [!code-vb[Formatting.DateAndTime.Custom#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandparsing1.vb#18)] + + The following table describes the custom date and time format specifiers and displays a result string produced by each format specifier. By default, result strings reflect the formatting conventions of the en-US culture. If a particular format specifier produces a localized result string, the example also notes the culture to which the result string applies. See the Notes section for additional information about using custom date and time format strings. + +| Format specifier | Description | Examples | +|----------------------|-----------------|--------------| +|"d"|The day of the month, from 1 through 31.

More information: [The "d" Custom Format Specifier](#dSpecifier).|2009-06-01T13:45:30 -> 1

2009-06-15T13:45:30 -> 15| +|"dd"|The day of the month, from 01 through 31.

More information: [The "dd" Custom Format Specifier](#ddSpecifier).|2009-06-01T13:45:30 -> 01

2009-06-15T13:45:30 -> 15| +|"ddd"|The abbreviated name of the day of the week.

More information: [The "ddd" Custom Format Specifier](#dddSpecifier).|2009-06-15T13:45:30 -> Mon (en-US)

2009-06-15T13:45:30 -> Пн (ru-RU)

2009-06-15T13:45:30 -> lun. (fr-FR)| +|"dddd"|The full name of the day of the week.

More information: [The "dddd" Custom Format Specifier](#ddddSpecifier).|2009-06-15T13:45:30 -> Monday (en-US)

2009-06-15T13:45:30 -> понедельник (ru-RU)

2009-06-15T13:45:30 -> lundi (fr-FR)| +|"f"|The tenths of a second in a date and time value.

More information: [The "f" Custom Format Specifier](#fSpecifier).|2009-06-15T13:45:30.6170000 -> 6

2009-06-15T13:45:30.05 -> 0| +|"ff"|The hundredths of a second in a date and time value.

More information: [The "ff" Custom Format Specifier](#ffSpecifier).|2009-06-15T13:45:30.6170000 -> 61

2009-06-15T13:45:30.0050000 -> 00| +|"fff"|The milliseconds in a date and time value.

More information: [The "fff" Custom Format Specifier](#fffSpecifier).|6/15/2009 13:45:30.617 -> 617

6/15/2009 13:45:30.0005 -> 000| +|"ffff"|The ten thousandths of a second in a date and time value.

More information: [The "ffff" Custom Format Specifier](#ffffSpecifier).|2009-06-15T13:45:30.6175000 -> 6175

2009-06-15T13:45:30.0000500 -> 0000| +|"fffff"|The hundred thousandths of a second in a date and time value.

More information: [The "fffff" Custom Format Specifier](#fffffSpecifier).|2009-06-15T13:45:30.6175400 -> 61754

6/15/2009 13:45:30.000005 -> 00000| +|"ffffff"|The millionths of a second in a date and time value.

More information: [The "ffffff" Custom Format Specifier](#ffffffSpecifier).|2009-06-15T13:45:30.6175420 -> 617542

2009-06-15T13:45:30.0000005 -> 000000| +|"fffffff"|The ten millionths of a second in a date and time value.

More information: [The "fffffff" Custom Format Specifier](#fffffffSpecifier).|2009-06-15T13:45:30.6175425 -> 6175425

2009-06-15T13:45:30.0001150 -> 0001150| +|"F"|If non-zero, the tenths of a second in a date and time value.

More information: [The "F" Custom Format Specifier](#F_Specifier).|2009-06-15T13:45:30.6170000 -> 6

2009-06-15T13:45:30.0500000 -> (no output)| +|"FF"|If non-zero, the hundredths of a second in a date and time value.

More information: [The "FF" Custom Format Specifier](#FF_Specifier).|2009-06-15T13:45:30.6170000 -> 61

2009-06-15T13:45:30.0050000 -> (no output)| +|"FFF"|If non-zero, the milliseconds in a date and time value.

More information: [The "FFF" Custom Format Specifier](#FFF_Specifier).|2009-06-15T13:45:30.6170000 -> 617

2009-06-15T13:45:30.0005000 -> (no output)| +|"FFFF"|If non-zero, the ten thousandths of a second in a date and time value.

More information: [The "FFFF" Custom Format Specifier](#FFFF_Specifier).|2009-06-15T13:45:30.5275000 -> 5275

2009-06-15T13:45:30.0000500 -> (no output)| +|"FFFFF"|If non-zero, the hundred thousandths of a second in a date and time value.

More information: [The "FFFFF" Custom Format Specifier](#FFFFF_Specifier).|2009-06-15T13:45:30.6175400 -> 61754

2009-06-15T13:45:30.0000050 -> (no output)| +|"FFFFFF"|If non-zero, the millionths of a second in a date and time value.

More information: [The "FFFFFF" Custom Format Specifier](#FFFFFF_Specifier).|2009-06-15T13:45:30.6175420 -> 617542

2009-06-15T13:45:30.0000005 -> (no output)| +|"FFFFFFF"|If non-zero, the ten millionths of a second in a date and time value.

More information: [The "FFFFFFF" Custom Format Specifier](#FFFFFFF_Specifier).|2009-06-15T13:45:30.6175425 -> 6175425

2009-06-15T13:45:30.0001150 -> 000115| +|"g", "gg"|The period or era.

More information: [The "g" or "gg" Custom Format Specifier](#gSpecifier).|2009-06-15T13:45:30.6170000 -> A.D.| +|"h"|The hour, using a 12-hour clock from 1 to 12.

More information: [The "h" Custom Format Specifier](#hSpecifier).|2009-06-15T01:45:30 -> 1

2009-06-15T13:45:30 -> 1| +|"hh"|The hour, using a 12-hour clock from 01 to 12.

More information: [The "hh" Custom Format Specifier](#hhSpecifier).|2009-06-15T01:45:30 -> 01

2009-06-15T13:45:30 -> 01| +|"H"|The hour, using a 24-hour clock from 0 to 23.

More information: [The "H" Custom Format Specifier](#H_Specifier).|2009-06-15T01:45:30 -> 1

2009-06-15T13:45:30 -> 13| +|"HH"|The hour, using a 24-hour clock from 00 to 23.

More information: [The "HH" Custom Format Specifier](#HH_Specifier).|2009-06-15T01:45:30 -> 01

2009-06-15T13:45:30 -> 13| +|"K"|Time zone information.

More information: [The "K" Custom Format Specifier](#KSpecifier).|With values:

2009-06-15T13:45:30, Kind Unspecified ->

2009-06-15T13:45:30, Kind Utc -> Z

2009-06-15T13:45:30, Kind Local -> -07:00 (depends on local computer settings)

With values:

2009-06-15T01:45:30-07:00 --> -07:00

2009-06-15T08:45:30+00:00 --> +00:00| +|"m"|The minute, from 0 through 59.

More information: [The "m" Custom Format Specifier](#mSpecifier).|2009-06-15T01:09:30 -> 9

2009-06-15T13:29:30 -> 29| +|"mm"|The minute, from 00 through 59.

More information: [The "mm" Custom Format Specifier](#mmSpecifier).|2009-06-15T01:09:30 -> 09

2009-06-15T01:45:30 -> 45| +|"M"|The month, from 1 through 12.

More information: [The "M" Custom Format Specifier](#M_Specifier).|2009-06-15T13:45:30 -> 6| +|"MM"|The month, from 01 through 12.

More information: [The "MM" Custom Format Specifier](#MM_Specifier).|2009-06-15T13:45:30 -> 06| +|"MMM"|The abbreviated name of the month.

More information: [The "MMM" Custom Format Specifier](#MMM_Specifier).|2009-06-15T13:45:30 -> Jun (en-US)

2009-06-15T13:45:30 -> juin (fr-FR)

2009-06-15T13:45:30 -> Jun (zu-ZA)| +|"MMMM"|The full name of the month.

More information: [The "MMMM" Custom Format Specifier](#MMMM_Specifier).|2009-06-15T13:45:30 -> June (en-US)

2009-06-15T13:45:30 -> juni (da-DK)

2009-06-15T13:45:30 -> uJuni (zu-ZA)| +|"s"|The second, from 0 through 59.

More information: [The "s" Custom Format Specifier](#sSpecifier).|2009-06-15T13:45:09 -> 9| +|"ss"|The second, from 00 through 59.

More information: [The "ss" Custom Format Specifier](#ssSpecifier).|2009-06-15T13:45:09 -> 09| +|"t"|The first character of the AM/PM designator.

More information: [The "t" Custom Format Specifier](#tSpecifier).|2009-06-15T13:45:30 -> P (en-US)

2009-06-15T13:45:30 -> 午 (ja-JP)

2009-06-15T13:45:30 -> (fr-FR)| +|"tt"|The AM/PM designator.

More information: [The "tt" Custom Format Specifier](#ttSpecifier).|2009-06-15T13:45:30 -> PM (en-US)

2009-06-15T13:45:30 -> 午後 (ja-JP)

2009-06-15T13:45:30 -> (fr-FR)| +|"y"|The year, from 0 to 99.

More information: [The "y" Custom Format Specifier](#ySpecifier).|0001-01-01T00:00:00 -> 1

0900-01-01T00:00:00 -> 0

1900-01-01T00:00:00 -> 0

2009-06-15T13:45:30 -> 9

2019-06-15T13:45:30 -> 19| +|"yy"|The year, from 00 to 99.

More information: [The "yy" Custom Format Specifier](#yySpecifier).|0001-01-01T00:00:00 -> 01

0900-01-01T00:00:00 -> 00

1900-01-01T00:00:00 -> 00

2019-06-15T13:45:30 -> 19| +|"yyy"|The year, with a minimum of three digits.

More information: [The "yyy" Custom Format Specifier](#yyySpecifier).|0001-01-01T00:00:00 -> 001

0900-01-01T00:00:00 -> 900

1900-01-01T00:00:00 -> 1900

2009-06-15T13:45:30 -> 2009| +|"yyyy"|The year as a four-digit number.

More information: [The "yyyy" Custom Format Specifier](#yyyySpecifier).|0001-01-01T00:00:00 -> 0001

0900-01-01T00:00:00 -> 0900

1900-01-01T00:00:00 -> 1900

2009-06-15T13:45:30 -> 2009| +|"yyyyy"|The year as a five-digit number.

More information: [The "yyyyy" Custom Format Specifier](#yyyyySpecifier).|0001-01-01T00:00:00 -> 00001

2009-06-15T13:45:30 -> 02009| +|"z"|Hours offset from UTC, with no leading zeros.

More information: [The "z" Custom Format Specifier](#zSpecifier).|2009-06-15T13:45:30-07:00 -> -7| +|"zz"|Hours offset from UTC, with a leading zero for a single-digit value.

More information: [The "zz" Custom Format Specifier](#zzSpecifier).|2009-06-15T13:45:30-07:00 -> -07| +|"zzz"|Hours and minutes offset from UTC.

More information: [The "zzz" Custom Format Specifier](#zzzSpecifier).|2009-06-15T13:45:30-07:00 -> -07:00| +|":"|The time separator.

More information: [The ":" Custom Format Specifier](#timeSeparator).|2009-06-15T13:45:30 -> : (en-US)

2009-06-15T13:45:30 -> . (it-IT)

2009-06-15T13:45:30 -> : (ja-JP)| +|"/"|The date separator.

More Information: [The "/" Custom Format Specifier](#dateSeparator).|2009-06-15T13:45:30 -> / (en-US)

2009-06-15T13:45:30 -> - (ar-DZ)

2009-06-15T13:45:30 -> . (tr-TR)| +|"*string*"

'*string*'|Literal string delimiter.

More information: [Character literals](#Literals).|2009-06-15T13:45:30 ("arr:" h:m t) -> arr: 1:45 P

2009-06-15T13:45:30 ('arr:' h:m t) -> arr: 1:45 P| +|%|Defines the following character as a custom format specifier.

More information:[Using Single Custom Format Specifiers](#UsingSingleSpecifiers).|2009-06-15T13:45:30 (%h) -> 1| +|\\|The escape character.

More information: [Character literals](#Literals) and [Using the Escape Character](#escape).|2009-06-15T13:45:30 (h \h) -> 1 h| +|Any other character|The character is copied to the result string unchanged.

More information: [Character literals](#Literals).|2009-06-15T01:45:30 (arr hh:mm t) -> arr 01:45 A| + + The following sections provide additional information about each custom date and time format specifier. Unless otherwise noted, each specifier produces an identical string representation regardless of whether it is used with a value or a value. + + +## The "d" custom format specifier + The "d" custom format specifier represents the day of the month as a number from 1 through 31. A single-digit day is formatted without a leading zero. + + If the "d" format specifier is used without other custom format specifiers, it is interpreted as the "d" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "d" custom format specifier in several format strings. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#1)] - [!code-vb[Formatting.DateAndTime.Custom#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#1)] - - [Back to table](#table) - - -## The "dd" custom format specifier - The "dd" custom format string represents the day of the month as a number from 01 through 31. A single-digit day is formatted with a leading zero. - - The following example includes the "dd" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#1)] + + [Back to table](#table) + + +## The "dd" custom format specifier + The "dd" custom format string represents the day of the month as a number from 01 through 31. A single-digit day is formatted with a leading zero. + + The following example includes the "dd" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#2)] - [!code-vb[Formatting.DateAndTime.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#2)] - - [Back to table](#table) - - -## The "ddd" custom format specifier - The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. - - The following example includes the "ddd" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#2)] + + [Back to table](#table) + + +## The "ddd" custom format specifier + The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. + + The following example includes the "ddd" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#3)] - [!code-vb[Formatting.DateAndTime.Custom#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#3)] - - [Back to table](#table) - - -## The "dddd" custom format specifier - The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. - - The following example includes the "dddd" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#3)] + + [Back to table](#table) + + +## The "dddd" custom format specifier + The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. + + The following example includes the "dddd" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#4)] - [!code-vb[Formatting.DateAndTime.Custom#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#4)] - - [Back to table](#table) - - -## The "f" custom format specifier - The "f" custom format specifier represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value. - - If the "f" format specifier is used without other format specifiers, it is interpreted as the "f" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - When you use "f" format specifiers as part of a format string supplied to the , , , or method, the number of "f" format specifiers indicates the number of most significant digits of the seconds fraction that must be present to successfully parse the string. - - The following example includes the "f" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#4)] + + [Back to table](#table) + + +## The "f" custom format specifier + The "f" custom format specifier represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value. + + If the "f" format specifier is used without other format specifiers, it is interpreted as the "f" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + When you use "f" format specifiers as part of a format string supplied to the , , , or method, the number of "f" format specifiers indicates the number of most significant digits of the seconds fraction that must be present to successfully parse the string. + + The following example includes the "f" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "ff" custom format specifier - The "ff" custom format specifier represents the two most significant digits of the seconds fraction; that is, it represents the hundredths of a second in a date and time value. - - following example includes the "ff" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "ff" custom format specifier + The "ff" custom format specifier represents the two most significant digits of the seconds fraction; that is, it represents the hundredths of a second in a date and time value. + + following example includes the "ff" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "fff" custom format specifier - The "fff" custom format specifier represents the three most significant digits of the seconds fraction; that is, it represents the milliseconds in a date and time value. - - The following example includes the "fff" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "fff" custom format specifier + The "fff" custom format specifier represents the three most significant digits of the seconds fraction; that is, it represents the milliseconds in a date and time value. + + The following example includes the "fff" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "ffff" custom format specifier - The "ffff" custom format specifier represents the four most significant digits of the seconds fraction; that is, it represents the ten thousandths of a second in a date and time value. - - Although it is possible to display the ten thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT version 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "fffff" custom format specifier - The "fffff" custom format specifier represents the five most significant digits of the seconds fraction; that is, it represents the hundred thousandths of a second in a date and time value. - - Although it is possible to display the hundred thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "ffffff" custom format specifier - The "ffffff" custom format specifier represents the six most significant digits of the seconds fraction; that is, it represents the millionths of a second in a date and time value. - - Although it is possible to display the millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "fffffff" custom format specifier - The "fffffff" custom format specifier represents the seven most significant digits of the seconds fraction; that is, it represents the ten millionths of a second in a date and time value. - - Although it is possible to display the ten millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "F" custom format specifier - The "F" custom format specifier represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value. Nothing is displayed if the digit is zero. - - If the "F" format specifier is used without other format specifiers, it is interpreted as the "F" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The number of "F" format specifiers used with the , , , or method indicates the maximum number of most significant digits of the seconds fraction that can be present to successfully parse the string. - - The following example includes the "F" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "ffff" custom format specifier + The "ffff" custom format specifier represents the four most significant digits of the seconds fraction; that is, it represents the ten thousandths of a second in a date and time value. + + Although it is possible to display the ten thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT version 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "fffff" custom format specifier + The "fffff" custom format specifier represents the five most significant digits of the seconds fraction; that is, it represents the hundred thousandths of a second in a date and time value. + + Although it is possible to display the hundred thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "ffffff" custom format specifier + The "ffffff" custom format specifier represents the six most significant digits of the seconds fraction; that is, it represents the millionths of a second in a date and time value. + + Although it is possible to display the millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "fffffff" custom format specifier + The "fffffff" custom format specifier represents the seven most significant digits of the seconds fraction; that is, it represents the ten millionths of a second in a date and time value. + + Although it is possible to display the ten millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "F" custom format specifier + The "F" custom format specifier represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value. Nothing is displayed if the digit is zero. + + If the "F" format specifier is used without other format specifiers, it is interpreted as the "F" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The number of "F" format specifiers used with the , , , or method indicates the maximum number of most significant digits of the seconds fraction that can be present to successfully parse the string. + + The following example includes the "F" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "FF" custom format specifier - The "FF" custom format specifier represents the two most significant digits of the seconds fraction; that is, it represents the hundredths of a second in a date and time value. However, trailing zeros or two zero digits are not displayed. - - The following example includes the "FF" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "FF" custom format specifier + The "FF" custom format specifier represents the two most significant digits of the seconds fraction; that is, it represents the hundredths of a second in a date and time value. However, trailing zeros or two zero digits are not displayed. + + The following example includes the "FF" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "FFF" custom format specifier - The "FFF" custom format specifier represents the three most significant digits of the seconds fraction; that is, it represents the milliseconds in a date and time value. However, trailing zeros or three zero digits are not displayed. - - The following example includes the "FFF" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "FFF" custom format specifier + The "FFF" custom format specifier represents the three most significant digits of the seconds fraction; that is, it represents the milliseconds in a date and time value. However, trailing zeros or three zero digits are not displayed. + + The following example includes the "FFF" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#5)] - [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] - - [Back to table](#table) - - -## The "FFFF" custom format specifier - The "FFFF" custom format specifier represents the four most significant digits of the seconds fraction; that is, it represents the ten thousandths of a second in a date and time value. However, trailing zeros or four zero digits are not displayed. - - Although it is possible to display the ten thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "FFFFF" custom format specifier - The "FFFFF" custom format specifier represents the five most significant digits of the seconds fraction; that is, it represents the hundred thousandths of a second in a date and time value. However, trailing zeros or five zero digits are not displayed. - - Although it is possible to display the hundred thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "FFFFFF" custom format specifier - The "FFFFFF" custom format specifier represents the six most significant digits of the seconds fraction; that is, it represents the millionths of a second in a date and time value. However, trailing zeros or six zero digits are not displayed. - - Although it is possible to display the millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On tfhe Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "FFFFFFF" custom format specifier - The "FFFFFFF" custom format specifier represents the seven most significant digits of the seconds fraction; that is, it represents the ten millionths of a second in a date and time value. However, trailing zeros or seven zero digits are not displayed. - - Although it is possible to display the ten millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - [Back to table](#table) - - -## The "g" or "gg" custom format specifier - The "g" or "gg" custom format specifiers (plus any number of additional "g" specifiers) represents the period or era, such as A.D. The formatting operation ignores this specifier if the date to be formatted does not have an associated period or era string. - - If the "g" format specifier is used without other custom format specifiers, it is interpreted as the "g" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "g" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#5)] + + [Back to table](#table) + + +## The "FFFF" custom format specifier + The "FFFF" custom format specifier represents the four most significant digits of the seconds fraction; that is, it represents the ten thousandths of a second in a date and time value. However, trailing zeros or four zero digits are not displayed. + + Although it is possible to display the ten thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "FFFFF" custom format specifier + The "FFFFF" custom format specifier represents the five most significant digits of the seconds fraction; that is, it represents the hundred thousandths of a second in a date and time value. However, trailing zeros or five zero digits are not displayed. + + Although it is possible to display the hundred thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "FFFFFF" custom format specifier + The "FFFFFF" custom format specifier represents the six most significant digits of the seconds fraction; that is, it represents the millionths of a second in a date and time value. However, trailing zeros or six zero digits are not displayed. + + Although it is possible to display the millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On tfhe Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "FFFFFFF" custom format specifier + The "FFFFFFF" custom format specifier represents the seven most significant digits of the seconds fraction; that is, it represents the ten millionths of a second in a date and time value. However, trailing zeros or seven zero digits are not displayed. + + Although it is possible to display the ten millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On the Windows NT 3.5 (and later) and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + [Back to table](#table) + + +## The "g" or "gg" custom format specifier + The "g" or "gg" custom format specifiers (plus any number of additional "g" specifiers) represents the period or era, such as A.D. The formatting operation ignores this specifier if the date to be formatted does not have an associated period or era string. + + If the "g" format specifier is used without other custom format specifiers, it is interpreted as the "g" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "g" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#6)] - [!code-vb[Formatting.DateAndTime.Custom#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#6)] - - [Back to table](#table) - - -## The "h" custom format specifier - The "h" custom format specifier represents the hour as a number from 1 through 12; that is, the hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. A particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted without a leading zero. For example, given a time of 5:43 in the morning or afternoon, this custom format specifier displays "5". - - If the "h" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "h" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#6)] + + [Back to table](#table) + + +## The "h" custom format specifier + The "h" custom format specifier represents the hour as a number from 1 through 12; that is, the hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. A particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted without a leading zero. For example, given a time of 5:43 in the morning or afternoon, this custom format specifier displays "5". + + If the "h" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "h" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#7)] - [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] - - [Back to table](#table) - - -## The "hh" custom format specifier - The "hh" custom format specifier (plus any number of additional "h" specifiers) represents the hour as a number from 01 through 12; that is, the hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. A particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted with a leading zero. For example, given a time of 5:43 in the morning or afternoon, this format specifier displays "05". - - The following example includes the "hh" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] + + [Back to table](#table) + + +## The "hh" custom format specifier + The "hh" custom format specifier (plus any number of additional "h" specifiers) represents the hour as a number from 01 through 12; that is, the hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. A particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted with a leading zero. For example, given a time of 5:43 in the morning or afternoon, this format specifier displays "05". + + The following example includes the "hh" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#8)] - [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] - - [Back to table](#table) - - -## The "H" custom format specifier - The "H" custom format specifier represents the hour as a number from 0 through 23; that is, the hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted without a leading zero. - - If the "H" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "H" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] + + [Back to table](#table) + + +## The "H" custom format specifier + The "H" custom format specifier represents the hour as a number from 0 through 23; that is, the hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted without a leading zero. + + If the "H" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "H" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#9](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#9)] - [!code-vb[Formatting.DateAndTime.Custom#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#9)] - - [Back to table](#table) - - -## The "HH" custom format specifier - The "HH" custom format specifier (plus any number of additional "H" specifiers) represents the hour as a number from 00 through 23; that is, the hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted with a leading zero. - - The following example includes the "HH" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#9)] + + [Back to table](#table) + + +## The "HH" custom format specifier + The "HH" custom format specifier (plus any number of additional "H" specifiers) represents the hour as a number from 00 through 23; that is, the hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted with a leading zero. + + The following example includes the "HH" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#10)] - [!code-vb[Formatting.DateAndTime.Custom#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#10)] - - [Back to table](#table) - - -## The "K" custom format specifier - The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: - -- For the local time zone (a property value of ), this specifier is equivalent to the "zzz" specifier and produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". - -- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. - -- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . - - For values, the "K" format specifier is equivalent to the "zzz" format specifier, and produces a result string containing the value's offset from UTC. - - If the "K" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example displays the string that results from using the "K" custom format specifier with various and values on a system in the U.S. Pacific Time zone. - + [!code-vb[Formatting.DateAndTime.Custom#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#10)] + + [Back to table](#table) + + +## The "K" custom format specifier + The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: + +- For the local time zone (a property value of ), this specifier is equivalent to the "zzz" specifier and produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". + +- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. + +- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . + + For values, the "K" format specifier is equivalent to the "zzz" format specifier, and produces a result string containing the value's offset from UTC. + + If the "K" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example displays the string that results from using the "K" custom format specifier with various and values on a system in the U.S. Pacific Time zone. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#12](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#12)] - [!code-vb[Formatting.DateAndTime.Custom#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#12)] - - [Back to table](#table) - - -## The "m" custom format specifier - The "m" custom format specifier represents the minute as a number from 0 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted without a leading zero. - - If the "m" format specifier is used without other custom format specifiers, it is interpreted as the "m" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "m" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#12)] + + [Back to table](#table) + + +## The "m" custom format specifier + The "m" custom format specifier represents the minute as a number from 0 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted without a leading zero. + + If the "m" format specifier is used without other custom format specifiers, it is interpreted as the "m" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "m" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#7)] - [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] - - [Back to table](#table) - - -## The "mm" custom format specifier - The "mm" custom format specifier (plus any number of additional "m" specifiers) represents the minute as a number from 00 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted with a leading zero. - - The following example includes the "mm" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] + + [Back to table](#table) + + +## The "mm" custom format specifier + The "mm" custom format specifier (plus any number of additional "m" specifiers) represents the minute as a number from 00 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted with a leading zero. + + The following example includes the "mm" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#8)] - [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] - - [Back to table](#table) - - -## The "M" custom format specifier - The "M" custom format specifier represents the month as a number from 1 through 12 (or from 1 through 13 for calendars that have 13 months). A single-digit month is formatted without a leading zero. - - If the "M" format specifier is used without other custom format specifiers, it is interpreted as the "M" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "M" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] + + [Back to table](#table) + + +## The "M" custom format specifier + The "M" custom format specifier represents the month as a number from 1 through 12 (or from 1 through 13 for calendars that have 13 months). A single-digit month is formatted without a leading zero. + + If the "M" format specifier is used without other custom format specifiers, it is interpreted as the "M" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "M" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#11](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#11)] - [!code-vb[Formatting.DateAndTime.Custom#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#11)] - - [Back to table](#table) - - -## The "MM" custom format specifier - The "MM" custom format specifier represents the month as a number from 01 through 12 (or from 1 through 13 for calendars that have 13 months). A single-digit month is formatted with a leading zero. - - The following example includes the "MM" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#11)] + + [Back to table](#table) + + +## The "MM" custom format specifier + The "MM" custom format specifier represents the month as a number from 01 through 12 (or from 1 through 13 for calendars that have 13 months). A single-digit month is formatted with a leading zero. + + The following example includes the "MM" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#2)] - [!code-vb[Formatting.DateAndTime.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#2)] - - [Back to table](#table) - - -## The "MMM" custom format specifier - The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. - - The following example includes the "MMM" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#2)] + + [Back to table](#table) + + +## The "MMM" custom format specifier + The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. + + The following example includes the "MMM" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#3)] - [!code-vb[Formatting.DateAndTime.Custom#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#3)] - - [Back to table](#table) - - -## The "MMMM" custom format specifier - The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. - - The following example includes the "MMMM" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#3)] + + [Back to table](#table) + + +## The "MMMM" custom format specifier + The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. + + The following example includes the "MMMM" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#4)] - [!code-vb[Formatting.DateAndTime.Custom#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#4)] - - [Back to table](#table) - - -## The "s" custom format specifier - The "s" custom format specifier represents the seconds as a number from 0 through 59. The result represents whole seconds that have passed since the last minute. A single-digit second is formatted without a leading zero. - - If the "s" format specifier is used without other custom format specifiers, it is interpreted as the "s" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "s" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#4)] + + [Back to table](#table) + + +## The "s" custom format specifier + The "s" custom format specifier represents the seconds as a number from 0 through 59. The result represents whole seconds that have passed since the last minute. A single-digit second is formatted without a leading zero. + + If the "s" format specifier is used without other custom format specifiers, it is interpreted as the "s" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "s" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#7)] - [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] - - [Back to table](#table) - - -## The "ss" custom format specifier - The "ss" custom format specifier (plus any number of additional "s" specifiers) represents the seconds as a number from 00 through 59. The result represents whole seconds that have passed since the last minute. A single-digit second is formatted with a leading zero. - - The following example includes the "ss" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] + + [Back to table](#table) + + +## The "ss" custom format specifier + The "ss" custom format specifier (plus any number of additional "s" specifiers) represents the seconds as a number from 00 through 59. The result represents whole seconds that have passed since the last minute. A single-digit second is formatted with a leading zero. + + The following example includes the "ss" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#8)] - [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] - - [Back to table](#table) - - -## The "t" custom format specifier - The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. - - If the "t" format specifier is used without other custom format specifiers, it is interpreted as the "t" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "t" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] + + [Back to table](#table) + + +## The "t" custom format specifier + The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. + + If the "t" format specifier is used without other custom format specifiers, it is interpreted as the "t" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "t" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#7)] - [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] - - [Back to table](#table) - - -## The "tt" custom format specifier - The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. - - Make sure to use the "tt" specifier for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. - - The following example includes the "tt" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#7)] + + [Back to table](#table) + + +## The "tt" custom format specifier + The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. + + Make sure to use the "tt" specifier for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. + + The following example includes the "tt" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#8)] - [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] - - [Back to table](#table) - - -## The "y" custom format specifier - The "y" custom format specifier represents the year as a one-digit or two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the first digit of a two-digit year begins with a zero (for example, 2008), the number is formatted without a leading zero. - - If the "y" format specifier is used without other custom format specifiers, it is interpreted as the "y" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "y" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#8)] + + [Back to table](#table) + + +## The "y" custom format specifier + The "y" custom format specifier represents the year as a one-digit or two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the first digit of a two-digit year begins with a zero (for example, 2008), the number is formatted without a leading zero. + + If the "y" format specifier is used without other custom format specifiers, it is interpreted as the "y" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "y" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#13)] - [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] - - [Back to table](#table) - - -## The "yy" custom format specifier - The "yy" custom format specifier represents the year as a two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the two-digit year has fewer than two significant digits, the number is padded with leading zeros to produce two digits. - - In a parsing operation, a two-digit year that is parsed using the "yy" custom format specifier is interpreted based on the property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. - + [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] + + [Back to table](#table) + + +## The "yy" custom format specifier + The "yy" custom format specifier represents the year as a two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the two-digit year has fewer than two significant digits, the number is padded with leading zeros to produce two digits. + + In a parsing operation, a two-digit year that is parsed using the "yy" custom format specifier is interpreted based on the property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#19](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/parseexact2digityear1.cs#19)] - [!code-vb[Formatting.DateAndTime.Custom#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/parseexact2digityear1.vb#19)] - - The following example includes the "yy" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/parseexact2digityear1.vb#19)] + + The following example includes the "yy" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#13)] - [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] - - [Back to table](#table) - - -## The "yyy" custom format specifier - The "yyy" custom format specifier represents the year with a minimum of three digits. If the year has more than three significant digits, they are included in the result string. If the year has fewer than three digits, the number is padded with leading zeros to produce three digits. - + [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] + + [Back to table](#table) + + +## The "yyy" custom format specifier + The "yyy" custom format specifier represents the year with a minimum of three digits. If the year has more than three significant digits, they are included in the result string. If the year has fewer than three digits, the number is padded with leading zeros to produce three digits. + > [!NOTE] -> For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays all significant digits. - - The following example includes the "yyy" custom format specifier in a custom format string. - +> For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays all significant digits. + + The following example includes the "yyy" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#13)] - [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] - - [Back to table](#table) - - -## The "yyyy" custom format specifier - The "yyyy" custom format specifier represents the year with a minimum of four digits. If the year has more than four significant digits, they are included in the result string. If the year has fewer than four digits, the number is padded with leading zeros to produce four digits. - + [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] + + [Back to table](#table) + + +## The "yyyy" custom format specifier + The "yyyy" custom format specifier represents the year with a minimum of four digits. If the year has more than four significant digits, they are included in the result string. If the year has fewer than four digits, the number is padded with leading zeros to produce four digits. + > [!NOTE] -> For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays a minimum of four digits. - - The following example includes the "yyyy" custom format specifier in a custom format string. - +> For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays a minimum of four digits. + + The following example includes the "yyyy" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#13)] - [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] - - [Back to table](#table) - - -## The "yyyyy" custom format specifier - The "yyyyy" custom format specifier (plus any number of additional "y" specifiers) represents the year with a minimum of five digits. If the year has more than five significant digits, they are included in the result string. If the year has fewer than five digits, the number is padded with leading zeros to produce five digits. - - If there are additional "y" specifiers, the number is padded with as many leading zeros as necessary to produce the number of "y" specifiers. - - The following example includes the "yyyyy" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] + + [Back to table](#table) + + +## The "yyyyy" custom format specifier + The "yyyyy" custom format specifier (plus any number of additional "y" specifiers) represents the year with a minimum of five digits. If the year has more than five significant digits, they are included in the result string. If the year has fewer than five digits, the number is padded with leading zeros to produce five digits. + + If there are additional "y" specifiers, the number is padded with as many leading zeros as necessary to produce the number of "y" specifiers. + + The following example includes the "yyyyy" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#13)] - [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] - - [Back to table](#table) - - -## The "z" custom format specifier - With values, the "z" custom format specifier represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. It does not reflect the value of an instance's property. For this reason, the "z" format specifier is not recommended for use with values. - - With values, this format specifier represents the value's offset from UTC in hours. - - The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted without a leading zero. - - If the "z" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - The following example includes the "z" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#13)] + + [Back to table](#table) + + +## The "z" custom format specifier + With values, the "z" custom format specifier represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. It does not reflect the value of an instance's property. For this reason, the "z" format specifier is not recommended for use with values. + + With values, this format specifier represents the value's offset from UTC in hours. + + The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted without a leading zero. + + If the "z" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + The following example includes the "z" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#14](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#14)] - [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] - - [Back to table](#table) - - -## The "zz" custom format specifier - With values, the "zz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours. It does not reflect the value of an instance's property. For this reason, the "zz" format specifier is not recommended for use with values. - - With values, this format specifier represents the value's offset from UTC in hours. - - The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. - - The following example includes the "zz" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] + + [Back to table](#table) + + +## The "zz" custom format specifier + With values, the "zz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours. It does not reflect the value of an instance's property. For this reason, the "zz" format specifier is not recommended for use with values. + + With values, this format specifier represents the value's offset from UTC in hours. + + The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. + + The following example includes the "zz" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#14](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#14)] - [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] - - [Back to table](#table) - - -## The "zzz" custom format specifier - With values, the "zzz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. It does not reflect the value of an instance's property. For this reason, the "zzz" format specifier is not recommended for use with values. - - With values, this format specifier represents the value's offset from UTC in hours and minutes. - - The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. - - The following example includes the "zzz" custom format specifier in a custom format string. - + [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] + + [Back to table](#table) + + +## The "zzz" custom format specifier + With values, the "zzz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. It does not reflect the value of an instance's property. For this reason, the "zzz" format specifier is not recommended for use with values. + + With values, this format specifier represents the value's offset from UTC in hours and minutes. + + The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. + + The following example includes the "zzz" custom format specifier in a custom format string. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#14](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/Custom1.cs#14)] - [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] - - [Back to table](#table) - - -## The ":" custom format specifier - The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. - + [!code-vb[Formatting.DateAndTime.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/Custom1.vb#14)] + + [Back to table](#table) + + +## The ":" custom format specifier + The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. + > [!NOTE] -> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "\_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. - - If the ":" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - [Back to table](#table) - - -## The "/" custom format specifier - The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. - +> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "\_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. + + If the ":" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + [Back to table](#table) + + +## The "/" custom format specifier + The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. + > [!NOTE] -> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. - - If the "/" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. - - [Back to table](#table) - - -## Character literals - The following characters in a custom date and time format string are reserved and are always interpreted as formatting characters or, in the case of ", ', /, and \\, as special characters. - -|||||| -|-|-|-|-|-| -|F|H|K|M|d| -|f|g|h|m|s| -|t|y|z|%|:| -|/|"|'|\|| - - All other characters are always interpreted as character literals and, in a formatting operation, are included in the result string unchanged. In a parsing operation, they must match the characters in the input string exactly; the comparison is case-sensitive. - - The following example includes the literal characters "PST" (for Pacific Standard Time) and "PDT" (for Pacific Daylight Time) to represent the local time zone in a format string. Note that the string is included in the result string, and that a string that includes the local time zone string also parses successfully. - +> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. + + If the "/" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. + + [Back to table](#table) + + +## Character literals + The following characters in a custom date and time format string are reserved and are always interpreted as formatting characters or, in the case of ", ', /, and \\, as special characters. + +|||||| +|-|-|-|-|-| +|F|H|K|M|d| +|f|g|h|m|s| +|t|y|z|%|:| +|/|"|'|\|| + + All other characters are always interpreted as character literals and, in a formatting operation, are included in the result string unchanged. In a parsing operation, they must match the characters in the input string exactly; the comparison is case-sensitive. + + The following example includes the literal characters "PST" (for Pacific Standard Time) and "PDT" (for Pacific Daylight Time) to represent the local time zone in a format string. Note that the string is included in the result string, and that a string that includes the local time zone string also parses successfully. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/LiteralsEx1.cs#20)] - [!code-vb[Formatting.DateAndTime.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx1.vb#20)] - - There are two ways to indicate that characters are to be interpreted as literal characters and not as reserve characters, so that they can be included in a result string or successfully parsed in an input string: - -- By escaping each reserved character. For more information, see [Using the Escape Character](#escape). - - The following example includes the literal characters "pst" (for Pacific Standard time) to represent the local time zone in a format string. Because both "s" and "t" are custom format strings, both characters must be escaped to be interpreted as character literals. - + [!code-vb[Formatting.DateAndTime.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx1.vb#20)] + + There are two ways to indicate that characters are to be interpreted as literal characters and not as reserve characters, so that they can be included in a result string or successfully parsed in an input string: + +- By escaping each reserved character. For more information, see [Using the Escape Character](#escape). + + The following example includes the literal characters "pst" (for Pacific Standard time) to represent the local time zone in a format string. Because both "s" and "t" are custom format strings, both characters must be escaped to be interpreted as character literals. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#21](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/LiteralsEx2.cs#21)] - [!code-vb[Formatting.DateAndTime.Custom#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx2.vb#21)] - -- By enclosing the entire literal string in quotation marks or apostrophes. The following example is like the previous one, except that "pst" is enclosed in quotation marks to indicate that the entire delimited string should be interpreted as character literals. - + [!code-vb[Formatting.DateAndTime.Custom#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx2.vb#21)] + +- By enclosing the entire literal string in quotation marks or apostrophes. The following example is like the previous one, except that "pst" is enclosed in quotation marks to indicate that the entire delimited string should be interpreted as character literals. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#22](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/LiteralsEx3.cs#22)] - [!code-vb[Formatting.DateAndTime.Custom#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx3.vb#22)] - - -## Notes - - -### Using single custom format specifiers - A custom date and time format string consists of two or more characters. Date and time formatting methods interpret any single-character string as a standard date and time format string. If they do not recognize the character as a valid format specifier, they throw a . For example, a format string that consists only of the specifier "h" is interpreted as a standard date and time format string. However, in this particular case, an exception is thrown because there is no "h" standard date and timeformat specifier. - - To use any of the custom date and time format specifiers as the only specifier in a format string (that is, to use the "d", "f", "F", "g", "h", "H", "K", "m", "M", "s", "t", "y", "z", ":", or "/" custom format specifier by itself), include a space before or after the specifier, or include a percent ("%") format specifier before the single custom date and time specifier. - - For example, "`%h"` is interpreted as a custom date and time format string that displays the hour represented by the current date and time value. You can also use the " h" or "h " format string, although this includes a space in the result string along with the hour. The following example illustrates these three format strings. - + [!code-vb[Formatting.DateAndTime.Custom#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/LiteralsEx3.vb#22)] + + +## Notes + + +### Using single custom format specifiers + A custom date and time format string consists of two or more characters. Date and time formatting methods interpret any single-character string as a standard date and time format string. If they do not recognize the character as a valid format specifier, they throw a . For example, a format string that consists only of the specifier "h" is interpreted as a standard date and time format string. However, in this particular case, an exception is thrown because there is no "h" standard date and timeformat specifier. + + To use any of the custom date and time format specifiers as the only specifier in a format string (that is, to use the "d", "f", "F", "g", "h", "H", "K", "m", "M", "s", "t", "y", "z", ":", or "/" custom format specifier by itself), include a space before or after the specifier, or include a percent ("%") format specifier before the single custom date and time specifier. + + For example, "`%h"` is interpreted as a custom date and time format string that displays the hour represented by the current date and time value. You can also use the " h" or "h " format string, although this includes a space in the result string along with the hour. The following example illustrates these three format strings. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#16](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/literal1.cs#16)] - [!code-vb[Formatting.DateAndTime.Custom#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/literal1.vb#16)] - - -### Using the Escape Character - The "d", "f", "F", "g", "h", "H", "K", "m", "M", "s", "t", "y", "z", ":", or "/" characters in a format string are interpreted as custom format specifiers rather than as literal characters. To prevent a character from being interpreted as a format specifier, you can precede it with a backslash (\\), which is the escape character. The escape character signifies that the following character is a character literal that should be included in the result string unchanged. - - To include a backslash in a result string, you must escape it with another backslash (`\\`). - + [!code-vb[Formatting.DateAndTime.Custom#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/literal1.vb#16)] + + +### Using the Escape Character + The "d", "f", "F", "g", "h", "H", "K", "m", "M", "s", "t", "y", "z", ":", or "/" characters in a format string are interpreted as custom format specifiers rather than as literal characters. To prevent a character from being interpreted as a format specifier, you can precede it with a backslash (\\), which is the escape character. The escape character signifies that the following character is a character literal that should be included in the result string unchanged. + + To include a backslash in a result string, you must escape it with another backslash (`\\`). + > [!NOTE] -> Some compilers, such as the C++ and C# compilers, may also interpret a single backslash character as an escape character. To ensure that a string is interpreted correctly when formatting, you can use the verbatim string literal character (the @ character) before the string in C#, or add another backslash character before each backslash in C# and C++. The following C# example illustrates both approaches. - - The following example uses the escape character to prevent the formatting operation from interpreting the "h" and "m" characters as format specifiers. - +> Some compilers, such as the C++ and C# compilers, may also interpret a single backslash character as an escape character. To ensure that a string is interpreted correctly when formatting, you can use the verbatim string literal character (the @ character) before the string in C#, or add another backslash character before each backslash in C# and C++. The following C# example illustrates both approaches. + + The following example uses the escape character to prevent the formatting operation from interpreting the "h" and "m" characters as format specifiers. + [!code-csharp-interactive[Formatting.DateAndTime.Custom#15](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/escape1.cs#15)] - [!code-vb[Formatting.DateAndTime.Custom#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/escape1.vb#15)] - -### Control Panel settings - The **Regional and Language Options** settings in Control Panel influence the result string produced by a formatting operation that includes many of the custom date and time format specifiers. These settings are used to initialize the object associated with the current thread culture, which provides values used to govern formatting. Computers that use different settings generate different result strings. - - In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. - -### DateTimeFormatInfo properties - Formatting is influenced by properties of the current object, which is provided implicitly by the current thread culture or explicitly by the parameter of the method that invokes formatting. For the parameter, you should specify a object, which represents a culture, or a object. - - The result string produced by many of the custom date and time format specifiers also depends on properties of the current object. Your application can change the result produced by some custom date and time format specifiers by changing the corresponding property. For example, the "ddd" format specifier adds an abbreviated weekday name found in the string array to the result string. Similarly, the "MMMM" format specifier adds a full month name found in the string array to the result string. - -## See Also - - - [Formatting Types](../../../docs/standard/base-types/formatting-types.md) - [Standard Date and Time Format Strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) + [!code-vb[Formatting.DateAndTime.Custom#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/escape1.vb#15)] + +### Control Panel settings + The **Regional and Language Options** settings in Control Panel influence the result string produced by a formatting operation that includes many of the custom date and time format specifiers. These settings are used to initialize the object associated with the current thread culture, which provides values used to govern formatting. Computers that use different settings generate different result strings. + + In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. + +### DateTimeFormatInfo properties + Formatting is influenced by properties of the current object, which is provided implicitly by the current thread culture or explicitly by the parameter of the method that invokes formatting. For the parameter, you should specify a object, which represents a culture, or a object. + + The result string produced by many of the custom date and time format specifiers also depends on properties of the current object. Your application can change the result produced by some custom date and time format specifiers by changing the corresponding property. For example, the "ddd" format specifier adds an abbreviated weekday name found in the string array to the result string. Similarly, the "MMMM" format specifier adds a full month name found in the string array to the result string. + +## See Also + + + [Formatting Types](../../../docs/standard/base-types/formatting-types.md) + [Standard Date and Time Format Strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) [Sample: .NET Framework 4 Formatting Utility](https://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d) diff --git a/docs/standard/base-types/custom-timespan-format-strings.md b/docs/standard/base-types/custom-timespan-format-strings.md index 1bc06f06fdd16..8cb690ff07103 100644 --- a/docs/standard/base-types/custom-timespan-format-strings.md +++ b/docs/standard/base-types/custom-timespan-format-strings.md @@ -17,375 +17,379 @@ author: "rpetrusha" ms.author: "ronpet" --- # Custom TimeSpan Format Strings -A format string defines the string representation of a value that results from a formatting operation. A custom format string consists of one or more custom format specifiers along with any number of literal characters. Any string that is not a [standard TimeSpan format string](../../../docs/standard/base-types/standard-timespan-format-strings.md) is interpreted as a custom format string. - + +A format string defines the string representation of a value that results from a formatting operation. A custom format string consists of one or more custom format specifiers along with any number of literal characters. Any string that is not a [standard TimeSpan format string](standard-timespan-format-strings.md) is interpreted as a custom format string. + > [!IMPORTANT] -> The custom format specifiers do not include placeholder separator symbols, such as the symbols that separate days from hours, hours from minutes, or seconds from fractional seconds. Instead, these symbols must be included in the custom format string as string literals. For example, `"dd\.hh\:mm"` defines a period (.) as the separator between days and hours, and a colon (:) as the separator between hours and minutes. -> -> Custom format specifiers also do not include a sign symbol that enables you to differentiate between negative and positive time intervals. To include a sign symbol, you have to construct a format string by using conditional logic. The [Other Characters](#Other) section includes an example. - - The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md) and [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. - - [!code-csharp[Conceptual.TimeSpan.Custom#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customformatexample1.cs#1)] - [!code-vb[Conceptual.TimeSpan.Custom#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customformatexample1.vb#1)] - - Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. - - [!code-csharp[Conceptual.TimeSpan.Custom#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customparseexample1.cs#2)] - [!code-vb[Conceptual.TimeSpan.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customparseexample1.vb#2)] - - The following table describes the custom date and time format specifiers. - -|Format specifier|Description|Example| -|----------------------|-----------------|-------------| -|"d", "%d"|The number of whole days in the time interval.

More information: [The "d" Custom Format Specifier](#dSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`%d` --> "6"

`d\.hh\:mm` --> "6.14:32"| -|"dd"-"dddddddd"|The number of whole days in the time interval, padded with leading zeros as needed.

More information: [The "dd"-"dddddddd" Custom Format Specifiers](#ddSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`ddd` --> "006"

`dd\.hh\:mm` --> "06.14:32"| -|"h", "%h"|The number of whole hours in the time interval that are not counted as part of days. Single-digit hours do not have a leading zero.

More information: [The "h" Custom Format Specifier](#hSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`%h` --> "14"

`hh\:mm` --> "14:32"| -|"hh"|The number of whole hours in the time interval that are not counted as part of days. Single-digit hours have a leading zero.

More information: [The "hh" Custom Format Specifier](#hhSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`hh` --> "14"

`new TimeSpan(6, 8, 32, 17, 685):`

`hh` --> 08| -|"m", "%m"|The number of whole minutes in the time interval that are not included as part of hours or days. Single-digit minutes do not have a leading zero.

More information: [The "m" Custom Format Specifier](#mSpecifier).|`new TimeSpan(6, 14, 8, 17, 685):`

`%m` --> "8"

`h\:m` --> "14:8"| -|"mm"|The number of whole minutes in the time interval that are not included as part of hours or days. Single-digit minutes have a leading zero.

More information: [The "mm" Custom Format Specifier](#mmSpecifier).|`new TimeSpan(6, 14, 8, 17, 685):`

`mm` --> "08"

`new TimeSpan(6, 8, 5, 17, 685):`

`d\.hh\:mm\:ss` --> 6.08:05:17| -|"s", "%s"|The number of whole seconds in the time interval that are not included as part of hours, days, or minutes. Single-digit seconds do not have a leading zero.

More information: [The "s" Custom Format Specifier](#sSpecifier).|`TimeSpan.FromSeconds(12.965)`:

`%s` --> 12

`s\.fff` --> 12.965| -|"ss"|The number of whole seconds in the time interval that are not included as part of hours, days, or minutes. Single-digit seconds have a leading zero.

More information: [The "ss" Custom Format Specifier](#ssSpecifier).|`TimeSpan.FromSeconds(6.965)`:

`ss` --> 06

`ss\.fff` --> 06.965| -|"f", "%f"|The tenths of a second in a time interval.

More information: [The "f" Custom Format Specifier](#fSpecifier).|`TimeSpan.FromSeconds(6.895)`:

`f` --> 8

`ss\.f` --> 06.8| -|"ff"|The hundredths of a second in a time interval.

More information:[The "ff" Custom Format Specifier](#ffSpecifier).|`TimeSpan.FromSeconds(6.895)`:

`ff` --> 89

`ss\.ff` --> 06.89| -|"fff"|The milliseconds in a time interval.

More information: [The "fff" Custom Format Specifier](#f3Specifier).|`TimeSpan.FromSeconds(6.895)`:

`fff` --> 895

`ss\.fff` --> 06.895| -|"ffff"|The ten-thousandths of a second in a time interval.

More information: [The "ffff" Custom Format Specifier](#f4Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`ffff` --> 8954

`ss\.ffff` --> 06.8954| -|"fffff"|The hundred-thousandths of a second in a time interval.

More information: [The "fffff" Custom Format Specifier](#f5Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`fffff` --> 89543

`ss\.fffff` --> 06.89543| -|"ffffff"|The millionths of a second in a time interval.

More information: [The "ffffff" Custom Format Specifier](#f6Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`ffffff` --> 895432

`ss\.ffffff` --> 06.895432| -|"fffffff"|The ten-millionths of a second (or the fractional ticks) in a time interval.

More information: [The "fffffff" Custom Format Specifier](#f7Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`fffffff` --> 8954321

`ss\.fffffff` --> 06.8954321| -|"F", "%F"|The tenths of a second in a time interval. Nothing is displayed if the digit is zero.

More information: [The "F" Custom Format Specifier](#F_Specifier).|`TimeSpan.Parse("00:00:06.32")`:

`%F`: 3

`TimeSpan.Parse("0:0:3.091")`:

`ss\.F`: 03.| -|"FF"|The hundredths of a second in a time interval. Any fractional trailing zeros or two zero digits are not included.

More information: [The "FF" Custom Format Specifier](#FF_Specifier).|`TimeSpan.Parse("00:00:06.329")`:

`FF`: 32

`TimeSpan.Parse("0:0:3.101")`:

`ss\.FF`: 03.1| -|"FFF"|The milliseconds in a time interval. Any fractional trailing zeros are not included.

More information:|`TimeSpan.Parse("00:00:06.3291")`:

`FFF`: 329

`TimeSpan.Parse("0:0:3.1009")`:

`ss\.FFF`: 03.1| -|"FFFF"|The ten-thousandths of a second in a time interval. Any fractional trailing zeros are not included.

More information: [The "FFFF" Custom Format Specifier](#F4_Specifier).|`TimeSpan.Parse("00:00:06.32917")`:

`FFFFF`: 3291

`TimeSpan.Parse("0:0:3.10009")`:

`ss\.FFFF`: 03.1| -|"FFFFF"|The hundred-thousandths of a second in a time interval. Any fractional trailing zeros are not included.

More information: [The "FFFFF" Custom Format Specifier](#F5_Specifier).|`TimeSpan.Parse("00:00:06.329179")`:

`FFFFF`: 32917

`TimeSpan.Parse("0:0:3.100009")`:

`ss\.FFFFF`: 03.1| -|"FFFFFF"|The millionths of a second in a time interval. Any fractional trailing zeros are not displayed.

More information: [The "FFFFFF" Custom Format Specifier](#F6_Specifier).|`TimeSpan.Parse("00:00:06.3291791")`:

`FFFFFF`: 329179

`TimeSpan.Parse("0:0:3.1000009")`:

`ss\.FFFFFF`: 03.1| -|"FFFFFFF"|The ten-millions of a second in a time interval. Any fractional trailing zeros or seven zeros are not displayed.

More information: [The "FFFFFFF" Custom Format Specifier](#F7_Specifier).|`TimeSpan.Parse("00:00:06.3291791")`:

`FFFFFF`: 3291791

`TimeSpan.Parse("0:0:3.1900000")`:

`ss\.FFFFFF`: 03.19| -|*'string*'|Literal string delimiter.

More information: [Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh':'mm':'ss` --> "14:32:17"| -|\\|The escape character.

More information:[Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh\:mm\:ss` --> "14:32:17"| -|Any other character|Any other unescaped character is interpreted as a custom format specifier.

More Information: [Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh\:mm\:ss` --> "14:32:17"| - - -## The "d" Custom Format Specifier - The "d" custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". - - If the "d" custom format specifier is used alone, specify "%d" so that it is not misinterpreted as a standard format string. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#3)] - [!code-vb[Conceptual.TimeSpan.Custom#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#3)] - - The following example illustrates the use of the "d" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#4)] - [!code-vb[Conceptual.TimeSpan.Custom#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#4)] - - [Back to table](#table) - - -## The "dd"-"dddddddd" Custom Format Specifiers - The "dd", "ddd", "dddd", "ddddd", "dddddd", "ddddddd", and "dddddddd" custom format specifiers output the value of the property, which represents the number of whole days in the time interval. - - The output string includes a minimum number of digits specified by the number of "d" characters in the format specifier, and it is padded with leading zeros as needed. If the digits in the number of days exceed the number of "d" characters in the format specifier, the full number of days is output in the result string. - - The following example uses these format specifiers to display the string representation of two values. The value of the days component of the first time interval is zero; the value of the days component of the second is 365. - - [!code-csharp[Conceptual.TimeSpan.Custom#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#5)] - [!code-vb[Conceptual.TimeSpan.Custom#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#5)] - - [Back to table](#table) - - -## The "h" Custom Format Specifier - The "h" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. - - If the "h" custom format specifier is used alone, specify "%h" so that it is not misinterpreted as a standard format string. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#6)] - [!code-vb[Conceptual.TimeSpan.Custom#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#6)] - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%h" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#8)] - [!code-vb[Conceptual.TimeSpan.Custom#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#8)] - - The following example illustrates the use of the "h" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#7)] - [!code-vb[Conceptual.TimeSpan.Custom#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#7)] - - [Back to table](#table) - - -## The "hh" Custom Format Specifier - The "hh" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "hh" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#9)] - [!code-vb[Conceptual.TimeSpan.Custom#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#9)] - - The following example illustrates the use of the "hh" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#10)] - [!code-vb[Conceptual.TimeSpan.Custom#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#10)] - - [Back to table](#table) - - -## The "m" Custom Format Specifier - The "m" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. - - If the "m" custom format specifier is used alone, specify "%m" so that it is not misinterpreted as a standard format string. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#6)] - [!code-vb[Conceptual.TimeSpan.Custom#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#6)] - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%m" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#11)] - [!code-vb[Conceptual.TimeSpan.Custom#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#11)] - - The following example illustrates the use of the "m" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#12)] - [!code-vb[Conceptual.TimeSpan.Custom#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#12)] - - [Back to table](#table) - - -## The "mm" Custom Format Specifier - The "mm" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "mm" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#13](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#13)] - [!code-vb[Conceptual.TimeSpan.Custom#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#13)] - - The following example illustrates the use of the "mm" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#14)] - [!code-vb[Conceptual.TimeSpan.Custom#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#14)] - - [Back to table](#table) - - -## The "s" Custom Format Specifier - The "s" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. - - If the "s" custom format specifier is used alone, specify "%s" so that it is not misinterpreted as a standard format string. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#15)] - [!code-vb[Conceptual.TimeSpan.Custom#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#15)] - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%s" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#17)] - [!code-vb[Conceptual.TimeSpan.Custom#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#17)] - - The following example illustrates the use of the "s" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#16](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#16)] - [!code-vb[Conceptual.TimeSpan.Custom#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#16)] - - [Back to table](#table) - - -## The "ss" Custom Format Specifier - The "ss" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. - - Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "ss" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. - - [!code-csharp[Conceptual.TimeSpan.Custom#18](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#18)] - [!code-vb[Conceptual.TimeSpan.Custom#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#18)] - - The following example illustrates the use of the "ss" custom format specifier. - - [!code-csharp[Conceptual.TimeSpan.Custom#19](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#19)] - [!code-vb[Conceptual.TimeSpan.Custom#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#19)] - - [Back to table](#table) - - -## The"f" Custom Format Specifier - The "f" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. - - If the "f" custom format specifier is used alone, specify "%f" so that it is not misinterpreted as a standard format string. - - The following example uses the "f" custom format specifier to display the tenths of a second in a value. "f" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "ff" Custom Format Specifier - The "ff" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. - - The following example uses the "ff" custom format specifier to display the hundredths of a second in a value. "ff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "fff" Custom Format Specifier - The "fff" custom format specifier (with three "f" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. - - The following example uses the "fff" custom format specifier to display the milliseconds in a value. "fff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "ffff" Custom Format Specifier - The "ffff" custom format specifier (with four "f" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. - - The following example uses the "ffff" custom format specifier to display the ten-thousandths of a second in a value. "ffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "fffff" Custom Format Specifier - The "fffff" custom format specifier (with five "f" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. - - The following example uses the "fffff" custom format specifier to display the hundred-thousandths of a second in a value. "fffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "ffffff" Custom Format Specifier - The "ffffff" custom format specifier (with six "f" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. - - The following example uses the "ffffff" custom format specifier to display the millionths of a second in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "fffffff" Custom Format Specifier - The "fffffff" custom format specifier (with seven "f" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. - - The following example uses the "fffffff" custom format specifier to display the fractional number of ticks in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. - - [!code-csharp[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] - [!code-vb[Conceptual.TimeSpan.Custom#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] - - [Back to table](#table) - - -## The "F" Custom Format Specifier - The "F" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it is not included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. - - If the "F" custom format specifier is used alone, specify "%F" so that it is not misinterpreted as a standard format string. - - The following example uses the "F" custom format specifier to display the tenths of a second in a value. It also uses this custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#21](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#21)] - [!code-vb[Conceptual.TimeSpan.Custom#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#21)] - - [Back to table](#table) - - -## The "FF" Custom Format Specifier - The "FF" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. - - The following example uses the "FF" custom format specifier to display the hundredths of a second in a value. It also uses this custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#22](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#22)] - [!code-vb[Conceptual.TimeSpan.Custom#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#22)] - - [Back to table](#table) - - -## The "FFF" Custom Format Specifier - The "FFF" custom format specifier (with three "F" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. - - The following example uses the "FFF" custom format specifier to display the thousandths of a second in a value. It also uses this custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#23](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#23)] - [!code-vb[Conceptual.TimeSpan.Custom#23](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#23)] - - [Back to table](#table) - - -## The "FFFF" Custom Format Specifier - The "FFFF" custom format specifier (with four "F" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. - - The following example uses the "FFFF" custom format specifier to display the ten-thousandths of a second in a value. It also uses the "FFFF" custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#24](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#24)] - [!code-vb[Conceptual.TimeSpan.Custom#24](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#24)] - - [Back to table](#table) - - -## The "FFFFF" Custom Format Specifier - The "FFFFF" custom format specifier (with five "F" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. - - The following example uses the "FFFFF" custom format specifier to display the hundred-thousandths of a second in a value. It also uses the "FFFFF" custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#25](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#25)] - [!code-vb[Conceptual.TimeSpan.Custom#25](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#25)] - - [Back to table](#table) - - -## The "FFFFFF" Custom Format Specifier - The "FFFFFF" custom format specifier (with six "F" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. - - The following example uses the "FFFFFF" custom format specifier to display the millionths of a second in a value. It also uses this custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#26](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#26)] - [!code-vb[Conceptual.TimeSpan.Custom#26](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#26)] - - [Back to table](#table) - - -## The "FFFFFFF" Custom Format Specifier - The "FFFFFFF" custom format specifier (with seven "F" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. - - The following example uses the "FFFFFFF" custom format specifier to display the fractional parts of a second in a value. It also uses this custom format specifier in a parsing operation. - - [!code-csharp[Conceptual.TimeSpan.Custom#27](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#27)] - [!code-vb[Conceptual.TimeSpan.Custom#27](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#27)] - - [Back to table](#table) - - -## Other Characters - Any other unescaped character in a format string, including a white-space character, is interpreted as a custom format specifier. In most cases, the presence of any other unescaped character results in a . - - There are two ways to include a literal character in a format string: - -- Enclose it in single quotation marks (the literal string delimiter). - -- Precede it with a backslash ("\\"), which is interpreted as an escape character. This means that, in C#, the format string must either be @-quoted, or the literal character must be preceded by an additional backslash. - - In some cases, you may have to use conditional logic to include an escaped literal in a format string. The following example uses conditional logic to include a sign symbol for negative time intervals. - - [!code-csharp[Conceptual.TimeSpan.Custom#29](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/negativevalues1.cs#29)] - [!code-vb[Conceptual.TimeSpan.Custom#29](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/negativevalues1.vb#29)] - - .NET does not define a grammar for separators in time intervals. This means that the separators between days and hours, hours and minutes, minutes and seconds, and seconds and fractions of a second must all be treated as character literals in a format string. - - The following example uses both the escape character and the single quote to define a custom format string that includes the word "minutes" in the output string. - - [!code-csharp[Conceptual.TimeSpan.Custom#28](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/literal1.cs#28)] - [!code-vb[Conceptual.TimeSpan.Custom#28](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/literal1.vb#28)] - - [Back to table](#table) - -## See Also - [Formatting Types](../../../docs/standard/base-types/formatting-types.md) - [Standard TimeSpan Format Strings](../../../docs/standard/base-types/standard-timespan-format-strings.md) +> The custom format specifiers do not include placeholder separator symbols, such as the symbols that separate days from hours, hours from minutes, or seconds from fractional seconds. Instead, these symbols must be included in the custom format string as string literals. For example, `"dd\.hh\:mm"` defines a period (.) as the separator between days and hours, and a colon (:) as the separator between hours and minutes. +> +> Custom format specifiers also do not include a sign symbol that enables you to differentiate between negative and positive time intervals. To include a sign symbol, you have to construct a format string by using conditional logic. The [Other Characters](#Other) section includes an example. + +The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](formatting-types.md) and [Composite Formatting](composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. + +[!code-csharp[Conceptual.TimeSpan.Custom#1](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customformatexample1.cs#1)] +[!code-vb[Conceptual.TimeSpan.Custom#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customformatexample1.vb#1)] + +Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. + +[!code-csharp[Conceptual.TimeSpan.Custom#2](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customparseexample1.cs#2)] +[!code-vb[Conceptual.TimeSpan.Custom#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customparseexample1.vb#2)] + + The following table describes the custom date and time format specifiers. + +| Format specifier | Description | Example | +|----------------------|-----------------|-------------| +|"d", "%d"|The number of whole days in the time interval.

More information: [The "d" Custom Format Specifier](#dSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`%d` --> "6"

`d\.hh\:mm` --> "6.14:32"| +|"dd"-"dddddddd"|The number of whole days in the time interval, padded with leading zeros as needed.

More information: [The "dd"-"dddddddd" Custom Format Specifiers](#ddSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`ddd` --> "006"

`dd\.hh\:mm` --> "06.14:32"| +|"h", "%h"|The number of whole hours in the time interval that are not counted as part of days. Single-digit hours do not have a leading zero.

More information: [The "h" Custom Format Specifier](#hSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`%h` --> "14"

`hh\:mm` --> "14:32"| +|"hh"|The number of whole hours in the time interval that are not counted as part of days. Single-digit hours have a leading zero.

More information: [The "hh" Custom Format Specifier](#hhSpecifier).|`new TimeSpan(6, 14, 32, 17, 685):`

`hh` --> "14"

`new TimeSpan(6, 8, 32, 17, 685):`

`hh` --> 08| +|"m", "%m"|The number of whole minutes in the time interval that are not included as part of hours or days. Single-digit minutes do not have a leading zero.

More information: [The "m" Custom Format Specifier](#mSpecifier).|`new TimeSpan(6, 14, 8, 17, 685):`

`%m` --> "8"

`h\:m` --> "14:8"| +|"mm"|The number of whole minutes in the time interval that are not included as part of hours or days. Single-digit minutes have a leading zero.

More information: [The "mm" Custom Format Specifier](#mmSpecifier).|`new TimeSpan(6, 14, 8, 17, 685):`

`mm` --> "08"

`new TimeSpan(6, 8, 5, 17, 685):`

`d\.hh\:mm\:ss` --> 6.08:05:17| +|"s", "%s"|The number of whole seconds in the time interval that are not included as part of hours, days, or minutes. Single-digit seconds do not have a leading zero.

More information: [The "s" Custom Format Specifier](#sSpecifier).|`TimeSpan.FromSeconds(12.965)`:

`%s` --> 12

`s\.fff` --> 12.965| +|"ss"|The number of whole seconds in the time interval that are not included as part of hours, days, or minutes. Single-digit seconds have a leading zero.

More information: [The "ss" Custom Format Specifier](#ssSpecifier).|`TimeSpan.FromSeconds(6.965)`:

`ss` --> 06

`ss\.fff` --> 06.965| +|"f", "%f"|The tenths of a second in a time interval.

More information: [The "f" Custom Format Specifier](#fSpecifier).|`TimeSpan.FromSeconds(6.895)`:

`f` --> 8

`ss\.f` --> 06.8| +|"ff"|The hundredths of a second in a time interval.

More information:[The "ff" Custom Format Specifier](#ffSpecifier).|`TimeSpan.FromSeconds(6.895)`:

`ff` --> 89

`ss\.ff` --> 06.89| +|"fff"|The milliseconds in a time interval.

More information: [The "fff" Custom Format Specifier](#f3Specifier).|`TimeSpan.FromSeconds(6.895)`:

`fff` --> 895

`ss\.fff` --> 06.895| +|"ffff"|The ten-thousandths of a second in a time interval.

More information: [The "ffff" Custom Format Specifier](#f4Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`ffff` --> 8954

`ss\.ffff` --> 06.8954| +|"fffff"|The hundred-thousandths of a second in a time interval.

More information: [The "fffff" Custom Format Specifier](#f5Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`fffff` --> 89543

`ss\.fffff` --> 06.89543| +|"ffffff"|The millionths of a second in a time interval.

More information: [The "ffffff" Custom Format Specifier](#f6Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`ffffff` --> 895432

`ss\.ffffff` --> 06.895432| +|"fffffff"|The ten-millionths of a second (or the fractional ticks) in a time interval.

More information: [The "fffffff" Custom Format Specifier](#f7Specifier).|`TimeSpan.Parse("0:0:6.8954321")`:

`fffffff` --> 8954321

`ss\.fffffff` --> 06.8954321| +|"F", "%F"|The tenths of a second in a time interval. Nothing is displayed if the digit is zero.

More information: [The "F" Custom Format Specifier](#F_Specifier).|`TimeSpan.Parse("00:00:06.32")`:

`%F`: 3

`TimeSpan.Parse("0:0:3.091")`:

`ss\.F`: 03.| +|"FF"|The hundredths of a second in a time interval. Any fractional trailing zeros or two zero digits are not included.

More information: [The "FF" Custom Format Specifier](#FF_Specifier).|`TimeSpan.Parse("00:00:06.329")`:

`FF`: 32

`TimeSpan.Parse("0:0:3.101")`:

`ss\.FF`: 03.1| +|"FFF"|The milliseconds in a time interval. Any fractional trailing zeros are not included.

More information:|`TimeSpan.Parse("00:00:06.3291")`:

`FFF`: 329

`TimeSpan.Parse("0:0:3.1009")`:

`ss\.FFF`: 03.1| +|"FFFF"|The ten-thousandths of a second in a time interval. Any fractional trailing zeros are not included.

More information: [The "FFFF" Custom Format Specifier](#F4_Specifier).|`TimeSpan.Parse("00:00:06.32917")`:

`FFFFF`: 3291

`TimeSpan.Parse("0:0:3.10009")`:

`ss\.FFFF`: 03.1| +|"FFFFF"|The hundred-thousandths of a second in a time interval. Any fractional trailing zeros are not included.

More information: [The "FFFFF" Custom Format Specifier](#F5_Specifier).|`TimeSpan.Parse("00:00:06.329179")`:

`FFFFF`: 32917

`TimeSpan.Parse("0:0:3.100009")`:

`ss\.FFFFF`: 03.1| +|"FFFFFF"|The millionths of a second in a time interval. Any fractional trailing zeros are not displayed.

More information: [The "FFFFFF" Custom Format Specifier](#F6_Specifier).|`TimeSpan.Parse("00:00:06.3291791")`:

`FFFFFF`: 329179

`TimeSpan.Parse("0:0:3.1000009")`:

`ss\.FFFFFF`: 03.1| +|"FFFFFFF"|The ten-millions of a second in a time interval. Any fractional trailing zeros or seven zeros are not displayed.

More information: [The "FFFFFFF" Custom Format Specifier](#F7_Specifier).|`TimeSpan.Parse("00:00:06.3291791")`:

`FFFFFF`: 3291791

`TimeSpan.Parse("0:0:3.1900000")`:

`ss\.FFFFFF`: 03.19| +|*'string*'|Literal string delimiter.

More information: [Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh':'mm':'ss` --> "14:32:17"| +|\\|The escape character.

More information:[Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh\:mm\:ss` --> "14:32:17"| +|Any other character|Any other unescaped character is interpreted as a custom format specifier.

More Information: [Other Characters](#Other).|`new TimeSpan(14, 32, 17):`

`hh\:mm\:ss` --> "14:32:17"| + + +## The "d" Custom Format Specifier + +The "d" custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". + +If the "d" custom format specifier is used alone, specify "%d" so that it is not misinterpreted as a standard format string. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#3](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#3)] +[!code-vb[Conceptual.TimeSpan.Custom#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#3)] + +The following example illustrates the use of the "d" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#4](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#4)] +[!code-vb[Conceptual.TimeSpan.Custom#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#4)] + +[Back to table](#table) + + +## The "dd"-"dddddddd" Custom Format Specifiers +The "dd", "ddd", "dddd", "ddddd", "dddddd", "ddddddd", and "dddddddd" custom format specifiers output the value of the property, which represents the number of whole days in the time interval. + +The output string includes a minimum number of digits specified by the number of "d" characters in the format specifier, and it is padded with leading zeros as needed. If the digits in the number of days exceed the number of "d" characters in the format specifier, the full number of days is output in the result string. + +The following example uses these format specifiers to display the string representation of two values. The value of the days component of the first time interval is zero; the value of the days component of the second is 365. + +[!code-csharp[Conceptual.TimeSpan.Custom#5](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#5)] +[!code-vb[Conceptual.TimeSpan.Custom#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#5)] + +[Back to table](#table) + + +## The "h" Custom Format Specifier +The "h" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. + +If the "h" custom format specifier is used alone, specify "%h" so that it is not misinterpreted as a standard format string. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#6](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#6)] +[!code-vb[Conceptual.TimeSpan.Custom#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#6)] + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%h" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#8](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#8)] +[!code-vb[Conceptual.TimeSpan.Custom#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#8)] + +The following example illustrates the use of the "h" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#7](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#7)] +[!code-vb[Conceptual.TimeSpan.Custom#7](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#7)] + +[Back to table](#table) + + +## The "hh" Custom Format Specifier +The "hh" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "hh" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#9](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#9)] +[!code-vb[Conceptual.TimeSpan.Custom#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#9)] + +The following example illustrates the use of the "hh" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#10](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#10)] +[!code-vb[Conceptual.TimeSpan.Custom#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#10)] + +[Back to table](#table) + + +## The "m" Custom Format Specifier +The "m" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. + +If the "m" custom format specifier is used alone, specify "%m" so that it is not misinterpreted as a standard format string. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#6](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#6)] +[!code-vb[Conceptual.TimeSpan.Custom#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#6)] + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%m" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#11](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#11)] +[!code-vb[Conceptual.TimeSpan.Custom#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#11)] + +The following example illustrates the use of the "m" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#12](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#12)] +[!code-vb[Conceptual.TimeSpan.Custom#12](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#12)] + +[Back to table](#table) + + +## The "mm" Custom Format Specifier +The "mm" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "mm" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#13](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#13)] +[!code-vb[Conceptual.TimeSpan.Custom#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#13)] + +The following example illustrates the use of the "mm" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#14](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#14)] +[!code-vb[Conceptual.TimeSpan.Custom#14](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#14)] + +[Back to table](#table) + + +## The "s" Custom Format Specifier +The "s" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. + +If the "s" custom format specifier is used alone, specify "%s" so that it is not misinterpreted as a standard format string. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#15](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#15)] +[!code-vb[Conceptual.TimeSpan.Custom#15](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#15)] + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%s" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#17](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#17)] +[!code-vb[Conceptual.TimeSpan.Custom#17](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#17)] + +The following example illustrates the use of the "s" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#16](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#16)] +[!code-vb[Conceptual.TimeSpan.Custom#16](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#16)] + +[Back to table](#table) + + +## The "ss" Custom Format Specifier +The "ss" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. + +Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "ss" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. + +[!code-csharp[Conceptual.TimeSpan.Custom#18](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#18)] +[!code-vb[Conceptual.TimeSpan.Custom#18](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#18)] + +The following example illustrates the use of the "ss" custom format specifier. + +[!code-csharp[Conceptual.TimeSpan.Custom#19](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customexamples1.cs#19)] +[!code-vb[Conceptual.TimeSpan.Custom#19](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customexamples1.vb#19)] + +[Back to table](#table) + + +## The"f" Custom Format Specifier +The "f" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. + +If the "f" custom format specifier is used alone, specify "%f" so that it is not misinterpreted as a standard format string. + +The following example uses the "f" custom format specifier to display the tenths of a second in a value. "f" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "ff" Custom Format Specifier +The "ff" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. + +The following example uses the "ff" custom format specifier to display the hundredths of a second in a value. "ff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "fff" Custom Format Specifier +The "fff" custom format specifier (with three "f" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. + +The following example uses the "fff" custom format specifier to display the milliseconds in a value. "fff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "ffff" Custom Format Specifier +The "ffff" custom format specifier (with four "f" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. + +The following example uses the "ffff" custom format specifier to display the ten-thousandths of a second in a value. "ffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "fffff" Custom Format Specifier +The "fffff" custom format specifier (with five "f" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. + +The following example uses the "fffff" custom format specifier to display the hundred-thousandths of a second in a value. "fffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "ffffff" Custom Format Specifier +The "ffffff" custom format specifier (with six "f" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. + +The following example uses the "ffffff" custom format specifier to display the millionths of a second in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "fffffff" Custom Format Specifier +The "fffffff" custom format specifier (with seven "f" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. + +The following example uses the "fffffff" custom format specifier to display the fractional number of ticks in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. + +[!code-csharp[Conceptual.TimeSpan.Custom#20](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/fspecifiers1.cs#20)] +[!code-vb[Conceptual.TimeSpan.Custom#20](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/fspecifiers1.vb#20)] + +[Back to table](#table) + + +## The "F" Custom Format Specifier +The "F" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it is not included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. + +If the "F" custom format specifier is used alone, specify "%F" so that it is not misinterpreted as a standard format string. + +The following example uses the "F" custom format specifier to display the tenths of a second in a value. It also uses this custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#21](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#21)] +[!code-vb[Conceptual.TimeSpan.Custom#21](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#21)] + +[Back to table](#table) + + +## The "FF" Custom Format Specifier +The "FF" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. + +The following example uses the "FF" custom format specifier to display the hundredths of a second in a value. It also uses this custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#22](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#22)] +[!code-vb[Conceptual.TimeSpan.Custom#22](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#22)] + +[Back to table](#table) + + +## The "FFF" Custom Format Specifier +The "FFF" custom format specifier (with three "F" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. + +The following example uses the "FFF" custom format specifier to display the thousandths of a second in a value. It also uses this custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#23](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#23)] +[!code-vb[Conceptual.TimeSpan.Custom#23](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#23)] + +[Back to table](#table) + + +## The "FFFF" Custom Format Specifier +The "FFFF" custom format specifier (with four "F" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. + +The following example uses the "FFFF" custom format specifier to display the ten-thousandths of a second in a value. It also uses the "FFFF" custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#24](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#24)] +[!code-vb[Conceptual.TimeSpan.Custom#24](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#24)] + +[Back to table](#table) + + +## The "FFFFF" Custom Format Specifier +The "FFFFF" custom format specifier (with five "F" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. + +The following example uses the "FFFFF" custom format specifier to display the hundred-thousandths of a second in a value. It also uses the "FFFFF" custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#25](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#25)] +[!code-vb[Conceptual.TimeSpan.Custom#25](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#25)] + +[Back to table](#table) + + +## The "FFFFFF" Custom Format Specifier +The "FFFFFF" custom format specifier (with six "F" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. + +The following example uses the "FFFFFF" custom format specifier to display the millionths of a second in a value. It also uses this custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#26](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#26)] +[!code-vb[Conceptual.TimeSpan.Custom#26](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#26)] + +[Back to table](#table) + + +## The "FFFFFFF" Custom Format Specifier +The "FFFFFFF" custom format specifier (with seven "F" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. + +The following example uses the "FFFFFFF" custom format specifier to display the fractional parts of a second in a value. It also uses this custom format specifier in a parsing operation. + +[!code-csharp[Conceptual.TimeSpan.Custom#27](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/f_specifiers1.cs#27)] +[!code-vb[Conceptual.TimeSpan.Custom#27](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/f_specifiers1.vb#27)] + +[Back to table](#table) + + +## Other Characters + +Any other unescaped character in a format string, including a white-space character, is interpreted as a custom format specifier. In most cases, the presence of any other unescaped character results in a . + +There are two ways to include a literal character in a format string: + +- Enclose it in single quotation marks (the literal string delimiter). + +- Precede it with a backslash ("\\"), which is interpreted as an escape character. This means that, in C#, the format string must either be @-quoted, or the literal character must be preceded by an additional backslash. + + In some cases, you may have to use conditional logic to include an escaped literal in a format string. The following example uses conditional logic to include a sign symbol for negative time intervals. + + [!code-csharp[Conceptual.TimeSpan.Custom#29](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/negativevalues1.cs#29)] + [!code-vb[Conceptual.TimeSpan.Custom#29](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/negativevalues1.vb#29)] + +.NET does not define a grammar for separators in time intervals. This means that the separators between days and hours, hours and minutes, minutes and seconds, and seconds and fractions of a second must all be treated as character literals in a format string. + +The following example uses both the escape character and the single quote to define a custom format string that includes the word "minutes" in the output string. + +[!code-csharp[Conceptual.TimeSpan.Custom#28](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/literal1.cs#28)] +[!code-vb[Conceptual.TimeSpan.Custom#28](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/literal1.vb#28)] + +[Back to table](#table) + +## See Also + +[Formatting Types](formatting-types.md) +[Standard TimeSpan Format Strings](standard-timespan-format-strings.md) diff --git a/docs/standard/base-types/enumeration-format-strings.md b/docs/standard/base-types/enumeration-format-strings.md index 9aa3084a5b018..508099b7ab454 100644 --- a/docs/standard/base-types/enumeration-format-strings.md +++ b/docs/standard/base-types/enumeration-format-strings.md @@ -14,32 +14,34 @@ author: "rpetrusha" ms.author: "ronpet" --- # Enumeration Format Strings -You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. - - The following table lists the enumeration formatting strings and the values they return. These format specifiers are not case-sensitive. - -| Format string | Result | -| ------------- | ------ | -| G or g | Displays the enumeration entry as a string value, if possible, and otherwise displays the integer value of the current instance. If the enumeration is defined with the **Flags** attribute set, the string values of each valid entry are concatenated together, separated by commas. If the **Flags** attribute is not set, an invalid value is displayed as a numeric entry. The following example illustrates the G format specifier.

[!code-csharp[Formatting.Enum#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#1)] [!code-vb[Formatting.Enum#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#1)] | -| F or f | Displays the enumeration entry as a string value, if possible. If the value can be completely displayed as a summation of the entries in the enumeration (even if the **Flags** attribute is not present), the string values of each valid entry are concatenated together, separated by commas. If the value cannot be completely determined by the enumeration entries, then the value is formatted as the integer value. The following example illustrates the F format specifier.

[!code-csharp[Formatting.Enum#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#2)] [!code-vb[Formatting.Enum#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#2)] | -| D or d | Displays the enumeration entry as an integer value in the shortest representation possible. The following example illustrates the D format specifier.

[!code-csharp[Formatting.Enum#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#3)] [!code-vb[Formatting.Enum#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#3)] | -| X or x | Displays the enumeration entry as a hexadecimal value. The value is represented with leading zeros as necessary, to ensure that the value is a minimum eight digits in length. The following example illustrates the X format specifier.

[!code-csharp[Formatting.Enum#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#4)] [!code-vb[Formatting.Enum#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#4)] | - -## Example - The following example defines an enumeration called `Colors` that consists of three entries: `Red`, `Blue`, and `Green`. - - [!code-csharp[Formatting.Enum#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#5)] - [!code-vb[Formatting.Enum#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#5)] - - After the enumeration is defined, an instance can be declared in the following manner. - - [!code-csharp[Formatting.Enum#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#6)] - [!code-vb[Formatting.Enum#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#6)] - - The `Color.ToString(System.String)` method can then be used to display the enumeration value in different ways, depending on the format specifier passed to it. - - [!code-csharp[Formatting.Enum#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#7)] - [!code-vb[Formatting.Enum#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#7)] - -## See Also - [Formatting Types](../../../docs/standard/base-types/formatting-types.md) +You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. + +The following table lists the enumeration formatting strings and the values they return. These format specifiers are not case-sensitive. + +| Format string | Result | +| ------------- | ------ | +| G or g | Displays the enumeration entry as a string value, if possible, and otherwise displays the integer value of the current instance. If the enumeration is defined with the **Flags** attribute set, the string values of each valid entry are concatenated together, separated by commas. If the **Flags** attribute is not set, an invalid value is displayed as a numeric entry. The following example illustrates the G format specifier.

[!code-csharp[Formatting.Enum#1](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#1)] [!code-vb[Formatting.Enum#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#1)] | +| F or f | Displays the enumeration entry as a string value, if possible. If the value can be completely displayed as a summation of the entries in the enumeration (even if the **Flags** attribute is not present), the string values of each valid entry are concatenated together, separated by commas. If the value cannot be completely determined by the enumeration entries, then the value is formatted as the integer value. The following example illustrates the F format specifier.

[!code-csharp[Formatting.Enum#2](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#2)] [!code-vb[Formatting.Enum#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#2)] | +| D or d | Displays the enumeration entry as an integer value in the shortest representation possible. The following example illustrates the D format specifier.

[!code-csharp[Formatting.Enum#3](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#3)] [!code-vb[Formatting.Enum#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#3)] | +| X or x | Displays the enumeration entry as a hexadecimal value. The value is represented with leading zeros as necessary, to ensure that the value is a minimum eight digits in length. The following example illustrates the X format specifier.

[!code-csharp[Formatting.Enum#4](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#4)] [!code-vb[Formatting.Enum#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#4)] | + +## Example + +The following example defines an enumeration called `Colors` that consists of three entries: `Red`, `Blue`, and `Green`. + +[!code-csharp[Formatting.Enum#5](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#5)] +[!code-vb[Formatting.Enum#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#5)] + +After the enumeration is defined, an instance can be declared in the following manner. + +[!code-csharp[Formatting.Enum#6](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#6)] +[!code-vb[Formatting.Enum#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#6)] + +The `Color.ToString(System.String)` method can then be used to display the enumeration value in different ways, depending on the format specifier passed to it. + +[!code-csharp[Formatting.Enum#7](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.Enum/cs/enum1.cs#7)] +[!code-vb[Formatting.Enum#7](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Enum/vb/enum1.vb#7)] + +## See Also + +[Formatting Types](formatting-types.md) \ No newline at end of file diff --git a/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md b/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md index f67bd41815540..98a93cb8f5bd2 100644 --- a/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md +++ b/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md @@ -14,55 +14,61 @@ author: "mairaw" ms.author: "mairaw" --- # WindowsRuntimeStreamExtensions.AsRandomAccessStream(System.IO.Stream) Method -[Supported in the .NET Framework 4.5.1 and later versions] - - Converts the specified stream to a random access stream. - - **Namespace:** - **Assembly:** System.Runtime.WindowsRuntime (in System.Runtime.WindowsRuntime.dll) - -## Syntax - -```csharp -[CLSCompliantAttribute(false)] -public static IRandomAccessStream AsRandomAccessStream(Stream stream) -``` - -```vb -'Declaration - _ - _ -Public Shared Function AsRandomAccessStream ( _ - stream As Stream) As IRandomAccessStream -``` - -#### Parameters - `stream` - - Type: -The stream to convert. - -## Return Value - Type: [Windows.Storage.Streams.RandomAccessStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.randomaccessstream.aspx) -A [!INCLUDE[wrt](../../../includes/wrt-md.md)] random access stream, which represents the converted stream. - -## Exceptions - -|Exception|Condition| -|---------------|---------------| -||The stream to convert does not support seeking.| - -## Remarks - This extension method is available only when you develop Windows Store apps. This method provides a convenient way of working with streams in Windows Store apps. The .NET Framework stream you want to convert must support seeking. For more information, see the method. - + +[Supported in the .NET Framework 4.5.1 and later versions] + +Converts the specified stream to a random access stream. + +**Namespace:** +**Assembly:** System.Runtime.WindowsRuntime (in System.Runtime.WindowsRuntime.dll) + +## Syntax + +```csharp +[CLSCompliantAttribute(false)] +public static IRandomAccessStream AsRandomAccessStream(Stream stream) +``` + +```vb +'Declaration + _ + _ +Public Shared Function AsRandomAccessStream ( _ + stream As Stream) As IRandomAccessStream +``` + +## Parameters + +`stream` + +Type: +The stream to convert. + +## Return Value + +Type: +A [!INCLUDE[wrt](../../../includes/wrt-md.md)] random access stream, which represents the converted stream. + +## Exceptions + +|Exception|Condition| +|---------------|---------------| +||The stream to convert does not support seeking.| + +## Remarks + +This extension method is available only when you develop Windows Store apps. This method provides a convenient way of working with streams in Windows Store apps. The .NET Framework stream you want to convert must support seeking. For more information, see the method. + > [!IMPORTANT] -> This API is supported in the .NET Framework 4.5.1 and later versions, but not in version 4.5. - -## Version Information - **.NET for Windows Store apps** - - Supported in: Windows 8.1 - -## See Also - `System.IO.WindowsRuntimeStreamExtensions` - [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](../../../docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md) +> This API is supported in the .NET Framework 4.5.1 and later versions, but not in version 4.5. + +## Version Information + +**.NET for Windows Store apps** + +Supported in: Windows 8.1 + +## See Also + +[System.IO.WindowsRuntimeStreamExtensions](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions(v=vs.110).aspx) +[How to: Convert Between .NET Framework Streams and Windows Runtime Streams](../io/how-to-convert-between-dotnet-streams-and-winrt-streams.md) \ No newline at end of file diff --git a/docs/standard/data/xml/extending-the-dom.md b/docs/standard/data/xml/extending-the-dom.md index 83483a5bcdc14..62dcbe748800c 100644 --- a/docs/standard/data/xml/extending-the-dom.md +++ b/docs/standard/data/xml/extending-the-dom.md @@ -10,237 +10,243 @@ author: "mairaw" ms.author: "mairaw" --- # Extending the DOM -The Microsoft .NET Framework includes a base set of classes that provides an implementation of the XML Document Object Model (DOM). The , and its derived classes, provides methods and properties that allow you to navigate, query, and modify the content and structure of an XML document. - - When XML content is loaded into memory using the DOM, the nodes created contain information such as node name, node type, and so on. There may be occasions where you require specific node information that the base classes do not provide. For example, you may want to see the line number and position of the node. In this case, you can derive new classes from the existing DOM classes and add additional functionality. - - There are two general guidelines when deriving new classes: - -- It is recommended that you never derive from the class. Instead, it is recommended that you derive classes from the class corresponding to the node type that you are interested in. For example, if you want to return additional information on attribute nodes, you can derive from the class. - -- Except for the node creation methods, it is recommended that when overriding a function, you should always call the base version of the function and then add any additional processing. - -## Creating Your Own Node Instances - The class contains node creation methods. When an XML file is loaded, these methods are called to create the nodes. You can override these methods so that your node instances are created when a document is loaded. For example, if you have extended the class, you would inherit the class and override the method. - - The following example shows how to override the method to return your implementation of the class. - -```vb -Class LineInfoDocument - Inherits XmlDocument - Public Overrides Function CreateElement(prefix As String, localname As String, nsURI As String) As XmlElement - Dim elem As New LineInfoElement(prefix, localname, nsURI, Me) - Return elem - End Function 'CreateElement -End Class 'LineInfoDocument -``` - -```csharp -class LineInfoDocument : XmlDocument { - public override XmlElement CreateElement(string prefix, string localname, string nsURI) { - LineInfoElement elem = new LineInfoElement(prefix, localname, nsURI, this); - return elem; - } -``` - -## Extending a Class - To extend a class, derive your class from one of the existing DOM classes. You can then override any of the virtual methods or properties in the base class, or add your own. - - In the following example, a new class is created, which implements the class and the interface. Additional methods and properties are defined which allows users to gather line information. - -```vb -Class LineInfoElement - Inherits XmlElement - Implements IXmlLineInfo - Private lineNumber As Integer = 0 - Private linePosition As Integer = 0 - - Friend Sub New(prefix As String, localname As String, nsURI As String, doc As XmlDocument) - MyBase.New(prefix, localname, nsURI, doc) - CType(doc, LineInfoDocument).IncrementElementCount() - End Sub 'New - - Public Sub SetLineInfo(linenum As Integer, linepos As Integer) - lineNumber = linenum - linePosition = linepos - End Sub 'SetLineInfo - - Public ReadOnly Property LineNumber() As Integer - Get - Return lineNumber - End Get - End Property - - Public ReadOnly Property LinePosition() As Integer - Get - Return linePosition - End Get - End Property - - Public Function HasLineInfo() As Boolean - Return True - End Function 'HasLineInfo -End Class 'LineInfoElement ' End LineInfoElement class. -``` - -```csharp -class LineInfoElement : XmlElement, IXmlLineInfo { - int lineNumber = 0; - int linePosition = 0; - internal LineInfoElement( string prefix, string localname, string nsURI, XmlDocument doc ) : base( prefix, localname, nsURI, doc ) { - ( (LineInfoDocument)doc ).IncrementElementCount(); - } - public void SetLineInfo( int linenum, int linepos ) { - lineNumber = linenum; - linePosition = linepos; - } - public int LineNumber { - get { - return lineNumber; - } - } - public int LinePosition { - get { - return linePosition; - } - } - public bool HasLineInfo() { - return true; - } -} // End LineInfoElement class. -``` - -### Example - The following example counts the number of elements in an XML document. - -```vb -Imports System -Imports System.Xml -Imports System.IO - - _ - -Class LineInfoDocument - Inherits XmlDocument - - Private elementCount As Integer - - Friend Sub New() - elementCount = 0 - End Sub 'New - - Public Overrides Function CreateElement(prefix As String, localname As String, nsURI As String) As XmlElement - Dim elem As New LineInfoElement(prefix, localname, nsURI, Me) - Return elem - End Function 'CreateElement - - Public Sub IncrementElementCount() - elementCount += 1 - End Sub 'IncrementElementCount - - Public Function GetCount() As Integer - Return elementCount - End Function 'GetCount -End Class 'LineInfoDocument - _ 'End LineInfoDocument class. - -Class LineInfoElement - Inherits XmlElement - - Friend Sub New(prefix As String, localname As String, nsURI As String, doc As XmlDocument) - MyBase.New(prefix, localname, nsURI, doc) - CType(doc, LineInfoDocument).IncrementElementCount() - End Sub 'New -End Class 'LineInfoElement - _ 'End LineInfoElement class. - -Public Class Test - - Private filename As [String] = "book.xml" - - Public Shared Sub Main() - - Dim doc As New LineInfoDocument() - doc.Load(filename) - Console.WriteLine("Number of elements in {0}: {1}", filename, doc.GetCount()) - End Sub 'Main -End Class 'Test -``` - -```csharp -using System; -using System.Xml; -using System.IO; - -class LineInfoDocument : XmlDocument { - - int elementCount; - internal LineInfoDocument():base() { - elementCount = 0; - } - - public override XmlElement CreateElement( string prefix, string localname, string nsURI) { - LineInfoElement elem = new LineInfoElement(prefix, localname, nsURI, this ); - return elem; - } - - public void IncrementElementCount() { - elementCount++; - } - - public int GetCount() { - return elementCount; - } -} // End LineInfoDocument class. - -class LineInfoElement:XmlElement { - - internal LineInfoElement( string prefix, string localname, string nsURI, XmlDocument doc ):base( prefix,localname,nsURI, doc ){ - ((LineInfoDocument)doc).IncrementElementCount(); - } -} // End LineInfoElement class. - -public class Test { - - const String filename = "book.xml"; - public static void Main() { - - LineInfoDocument doc =new LineInfoDocument(); - doc.Load(filename); - Console.WriteLine("Number of elements in {0}: {1}", filename, doc.GetCount()); - - } -} -``` - -##### Input - book.xml - -```xml - - - The Handmaid's Tale - 14.95 - -``` - -##### Output - -``` -Number of elements in book.xml: 3 -``` - - For an example showing how to extend the XML DOM classes (System.Xml), see www.gotdotnet.com/userfiles/XMLDom/extendDOM.zip. - -## Node Event Handler - The .NET Framework implementation of the DOM also includes an event system that enables you to receive and handle events when nodes in an XML document change. Using the and classes, you can capture `NodeChanged`, `NodeChanging`, `NodeInserted`, `NodeInserting`, `NodeRemoved`, and `NodeRemoving` events. - - The event-handling process works exactly the same in derived classes as it would in the original DOM classes. - - For more information regarding node event handling, see [Events](../../../../docs/standard/events/index.md) and . - -## Default Attributes and the CreateElement Method - If you are overriding the method in a derived class, default attributes are not added when you are creating new elements while editing the document. This is only an issue while editing. Because the method is responsible for adding default attributes to an , you must code this functionality in the method. If you are loading an that includes default attributes, they will be handled correctly. For more information on default attributes, see [Creating New Attributes for Elements in the DOM](../../../../docs/standard/data/xml/creating-new-attributes-for-elements-in-the-dom.md). - -## See Also - [XML Document Object Model (DOM)](../../../../docs/standard/data/xml/xml-document-object-model-dom.md) + +The Microsoft .NET Framework includes a base set of classes that provides an implementation of the XML Document Object Model (DOM). The , and its derived classes, provides methods and properties that allow you to navigate, query, and modify the content and structure of an XML document. + +When XML content is loaded into memory using the DOM, the nodes created contain information such as node name, node type, and so on. There may be occasions where you require specific node information that the base classes do not provide. For example, you may want to see the line number and position of the node. In this case, you can derive new classes from the existing DOM classes and add additional functionality. + +There are two general guidelines when deriving new classes: + +- It is recommended that you never derive from the class. Instead, it is recommended that you derive classes from the class corresponding to the node type that you are interested in. For example, if you want to return additional information on attribute nodes, you can derive from the class. + +- Except for the node creation methods, it is recommended that when overriding a function, you should always call the base version of the function and then add any additional processing. + +## Creating Your Own Node Instances + +The class contains node creation methods. When an XML file is loaded, these methods are called to create the nodes. You can override these methods so that your node instances are created when a document is loaded. For example, if you have extended the class, you would inherit the class and override the method. + +The following example shows how to override the method to return your implementation of the class. + +```vb +Class LineInfoDocument + Inherits XmlDocument + Public Overrides Function CreateElement(prefix As String, localname As String, nsURI As String) As XmlElement + Dim elem As New LineInfoElement(prefix, localname, nsURI, Me) + Return elem + End Function 'CreateElement +End Class 'LineInfoDocument +``` + +```csharp +class LineInfoDocument : XmlDocument +{ + public override XmlElement CreateElement(string prefix, string localname, string nsURI) + { + LineInfoElement elem = new LineInfoElement(prefix, localname, nsURI, this); + return elem; + } +} +``` + +## Extending a Class + +To extend a class, derive your class from one of the existing DOM classes. You can then override any of the virtual methods or properties in the base class, or add your own. + +In the following example, a new class is created, which implements the class and the interface. Additional methods and properties are defined which allows users to gather line information. + +```vb +Class LineInfoElement + Inherits XmlElement + Implements IXmlLineInfo + Private lineNumber As Integer = 0 + Private linePosition As Integer = 0 + + Friend Sub New(prefix As String, localname As String, nsURI As String, doc As XmlDocument) + MyBase.New(prefix, localname, nsURI, doc) + CType(doc, LineInfoDocument).IncrementElementCount() + End Sub + + Public Sub SetLineInfo(linenum As Integer, linepos As Integer) + lineNumber = linenum + linePosition = linepos + End Sub + + Public ReadOnly Property LineNumber() As Integer + Get + Return lineNumber + End Get + End Property + + Public ReadOnly Property LinePosition() As Integer + Get + Return linePosition + End Get + End Property + + Public Function HasLineInfo() As Boolean + Return True + End Function +End Class ' End LineInfoElement class. +``` + +```csharp +class LineInfoElement : XmlElement, IXmlLineInfo { + int lineNumber = 0; + int linePosition = 0; + internal LineInfoElement( string prefix, string localname, string nsURI, XmlDocument doc ) : base( prefix, localname, nsURI, doc ) { + ( (LineInfoDocument)doc ).IncrementElementCount(); + } + public void SetLineInfo( int linenum, int linepos ) { + lineNumber = linenum; + linePosition = linepos; + } + public int LineNumber { + get { + return lineNumber; + } + } + public int LinePosition { + get { + return linePosition; + } + } + public bool HasLineInfo() { + return true; + } +} // End LineInfoElement class. +``` + +### Example + +The following example counts the number of elements in an XML document: + +```vb +Imports System +Imports System.Xml +Imports System.IO + +Class LineInfoDocument + Inherits XmlDocument + + Private elementCount As Integer + + Friend Sub New() + elementCount = 0 + End Sub + + Public Overrides Function CreateElement(prefix As String, localname As String, nsURI As String) As XmlElement + Dim elem As New LineInfoElement(prefix, localname, nsURI, Me) + Return elem + End Function + + Public Sub IncrementElementCount() + elementCount += 1 + End Sub + + Public Function GetCount() As Integer + Return elementCount + End Function +End Class 'End LineInfoDocument class. + +Class LineInfoElement + Inherits XmlElement + + Friend Sub New(prefix As String, localname As String, nsURI As String, doc As XmlDocument) + MyBase.New(prefix, localname, nsURI, doc) + CType(doc, LineInfoDocument).IncrementElementCount() + End Sub 'New +End Class 'LineInfoElement + _ 'End LineInfoElement class. + +Public Class Test + + Private filename As [String] = "book.xml" + + Public Shared Sub Main() + + Dim doc As New LineInfoDocument() + doc.Load(filename) + Console.WriteLine("Number of elements in {0}: {1}", filename, doc.GetCount()) + End Sub +End Class +``` + +```csharp +using System; +using System.Xml; +using System.IO; + +class LineInfoDocument : XmlDocument { + + int elementCount; + internal LineInfoDocument():base() { + elementCount = 0; + } + + public override XmlElement CreateElement( string prefix, string localname, string nsURI) { + LineInfoElement elem = new LineInfoElement(prefix, localname, nsURI, this ); + return elem; + } + + public void IncrementElementCount() { + elementCount++; + } + + public int GetCount() { + return elementCount; + } +} // End LineInfoDocument class. + +class LineInfoElement:XmlElement { + + internal LineInfoElement( string prefix, string localname, string nsURI, XmlDocument doc ):base( prefix,localname,nsURI, doc ){ + ((LineInfoDocument)doc).IncrementElementCount(); + } +} // End LineInfoElement class. + +public class Test { + + const String filename = "book.xml"; + public static void Main() { + + LineInfoDocument doc =new LineInfoDocument(); + doc.Load(filename); + Console.WriteLine("Number of elements in {0}: {1}", filename, doc.GetCount()); + + } +} +``` + +#### Input + +book.xml + +```xml + + + The Handmaid's Tale + 14.95 + +``` + +#### Output + +```console +Number of elements in book.xml: 3 +``` + +## Node Event Handler + +The .NET Framework implementation of the DOM also includes an event system that enables you to receive and handle events when nodes in an XML document change. Using the and classes, you can capture `NodeChanged`, `NodeChanging`, `NodeInserted`, `NodeInserting`, `NodeRemoved`, and `NodeRemoving` events. + +The event-handling process works exactly the same in derived classes as it would in the original DOM classes. + +For more information regarding node event handling, see [Events](../../../../docs/standard/events/index.md) and . + +## Default Attributes and the CreateElement Method + +If you are overriding the method in a derived class, default attributes are not added when you are creating new elements while editing the document. This is only an issue while editing. Because the method is responsible for adding default attributes to an , you must code this functionality in the method. If you are loading an that includes default attributes, they will be handled correctly. For more information on default attributes, see [Creating New Attributes for Elements in the DOM](creating-new-attributes-for-elements-in-the-dom.md). + +## See Also + +[XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/implementation-of-discretionary-behaviors-in-the-xsltransform-class.md b/docs/standard/data/xml/implementation-of-discretionary-behaviors-in-the-xsltransform-class.md index 686f463bab9a7..041d34f3607fa 100644 --- a/docs/standard/data/xml/implementation-of-discretionary-behaviors-in-the-xsltransform-class.md +++ b/docs/standard/data/xml/implementation-of-discretionary-behaviors-in-the-xsltransform-class.md @@ -7,74 +7,79 @@ author: "mairaw" ms.author: "mairaw" --- # Implementation of Discretionary Behaviors in the XslTransform Class + > [!NOTE] -> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](../../../../docs/standard/data/xml/using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](../../../../docs/standard/data/xml/migrating-from-the-xsltransform-class.md) for more information. - - Discretionary behaviors are described as behaviors listed in the World Wide Web Consortium (W3C) XSL Transformations (XSLT) Version 1.0 Recommendation (www.w3.org/TR/xslt), in which the implementation provider chooses one of several possible options as a way to handle a situation. For example, in section 7.3 Creating Processing Instructions, the W3C Recommendation says that it is an error if instantiating the content of `xsl:processing-instruction` creates nodes other than text nodes. For some problems, the W3C tells what decision should be made if the processor decides to recover from the error. For the problem given in section 7.3, the W3C says that the implementation can recover from this error by ignoring the nodes and their content. - - Therefore, for each of the discretionary behaviors allowed by the W3C, the table below lists the discretionary behaviors implemented for the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] implementation of the class, and what section in the W3C XSLT 1.0 Recommendation that this problem is discussed. - -|Problem|Behavior|Section| -|-------------|--------------|-------------| -|A text node matches both `xsl:strip-space` and `xsl:preserve-space`.|Recover|3.4| -|A source node matches more than one template rule.|Recover|5.5| -|A namespace Uniform Resource Identifier (URI) is declared to be an alias for multiple namespace URIs, all having the same import precedence.|Recover|7.1.1| -|The name attribute in `xsl:attribute` and `xsl:element` generated from an attribute value template is not a valid qualified name (QName).|Exception thrown|7.1.2 and 7.1.3| -|Adding an attribute to an element after child nodes have already been added to the element node.|Recover|7.1.3| -|Adding an attribute to anything other than an element node.|Recover|7.1.3| -|Instantiation of the content of the `xsl:attribute` element is not a text node.|Recover|7.1.3| -|Two attribute sets have the same import precedence and expanded name. Both have the same attribute, and there is no other attribute set containing the common attribute with the same name with higher importance.|Recover|7.1.4| -|`xsl:processing-instruction` name attribute does not yield both a no-colon name (NCName) and a Processing Instruction target.|Recover|7.3| -|Instantiating the content of `xsl:processing-instruction` creates nodes other than text nodes.|Recover|7.3| -|Results of instantiating the content of the `xsl:processing-instruction` contains the string "`?>`".|Recover|7.3| -|Results of instantiating the content of the `xsl:comment` contains the string "--", or ends with "-".|Recover|7.4| -|Results of instantiating the content of the `xsl:comment` creates nodes other than text nodes.|Recover|7.4| -|The template within a variable-binding element returns an attribute node or a namespace node.|Recover|11.2| -|There is an error retrieving the resource from the URI passed into the document function.|Exception thrown|12.1| -|The URI reference in the document function contains a fragment identifier, and there is an error processing the fragment identifier.|Exception thrown|12.1| -|There are multiple attributes with the same name that are not named `cdata-section-elements` in `xls:output`, and these attributes have the same import precedence.|Recover|16| -|The processor does not support the character encoding value given in the `encoding` attribute of the `xsl:output` element.|Recover|16.1| -|`disable-output-escaping` is used for a text node, and that text node is used to create something other than a text node in the result tree.|`disable-output-escaping` attribute is ignored|16.4| -|Converting a result tree fragment to a number or string if the result tree fragment contains a text node with output escaping enabled.|Ignored|16.4| -|Output escaping is disabled for characters that cannot be represented in the encoding that the XSLT processor is using for output.|Ignored|16.4| -|Adding a namespace node to an element after children have been added to it or after attributes have been added to it|Recover|Errata e25| -|`xsl:number` is NaN, infinite, or less than 0.5.|Recover|Errata e24| -|The second argument node-set to the document function is empty and the URI reference is relative|Recover|Errata e14| - - Sections from the errata can be found in the World Wide Web Consortium (W3C) XSL Transformations (XSLT) Version 1.0 Specification Errata, located at www.w3.org/1999/11/REC-xslt-19991116-errata. - -## Custom-Defined Implementation Behaviors - There are behaviors unique to the class implementation. This section discusses the provider-specific implementation of the `xsl:sort` and optional features that are supported by the class. - -## xsl:sort - When using a transformation to sort, the W3C XSLT 1.0 Recommendation makes some observations. They are: - -- Two XSLT processors may be conforming processors, but still may sort differently. - -- Not all XSLT processors support the same languages. - -- With regard to languages, different processors may vary on their sorting on a particular language not specified on the `xsl:sort.` - - The following table shows the sorting behavior implemented for each data type in the .NET Framework implementation of a transformation using . - -|Data type|Sorting behavior| -|---------------|----------------------| -|Text|Data is sorted using the common language runtime (CLR) String.Compare method, and the cultural locale. When the data type equals "text", sorting in the class behaves identically to the string comparison behaviors of the CLR.| -|Number|Numeric values are treated as XML Path Language (XPath) numbers and are sorted according to the details outlined in the W3C XML Path Language (XPath) Version 1.0 Recommendation, Section 3.5 (www.w3.org/TR/xpath.html#numbers).| - -## Optional Features Supported - The following table shows the features that are optional for an XSLT processor to implement and are implemented in the class. - -|Feature|Reference location|Notes| -|-------------|------------------------|-----------| -|`disable-output-escaping` attribute on `` and `` tags.|W3C XSLT 1.0 Recommendation,

Section 16.4|The `disable-output-escaping` attribute is ignored when the `xsl:text` or `xsl:value-of` elements are used in an `xsl:comment`, `xsl:processing-instruction`, or `xsl:attribute` element.

Result tree fragments that contain text and the text output that has been escaped are not supported.

The disable-output-escaping attribute is ignored when transforming to an or object.| - -## See Also - - [XslTransform Class Implements the XSLT Processor](../../../../docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md) - [XSLT Transformations with the XslTransform Class](../../../../docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md) - [XPathNavigator in Transformations](../../../../docs/standard/data/xml/xpathnavigator-in-transformations.md) - [XPathNodeIterator in Transformations](../../../../docs/standard/data/xml/xpathnodeiterator-in-transformations.md) - [XPathDocument Input to XslTransform](../../../../docs/standard/data/xml/xpathdocument-input-to-xsltransform.md) - [XmlDataDocument Input to XslTransform](../../../../docs/standard/data/xml/xmldatadocument-input-to-xsltransform.md) - [XmlDocument Input to XslTransform](../../../../docs/standard/data/xml/xmldocument-input-to-xsltransform.md) +> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) for more information. + +Discretionary behaviors are described as behaviors listed in the [World Wide Web Consortium (W3C) XSL Transformations (XSLT) Version 1.0 Recommendation](https://www.w3.org/TR/1999/REC-xslt-19991116), in which the implementation provider chooses one of several possible options as a way to handle a situation. For example, in section 7.3 Creating Processing Instructions, the W3C Recommendation says that it is an error if instantiating the content of `xsl:processing-instruction` creates nodes other than text nodes. For some problems, the W3C tells what decision should be made if the processor decides to recover from the error. For the problem given in section 7.3, the W3C says that the implementation can recover from this error by ignoring the nodes and their content. + +Therefore, for each of the discretionary behaviors allowed by the W3C, the table below lists the discretionary behaviors implemented for the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] implementation of the class, and what section in the W3C XSLT 1.0 Recommendation that this problem is discussed. + +|Problem|Behavior|Section| +|-------------|--------------|-------------| +|A text node matches both `xsl:strip-space` and `xsl:preserve-space`.|Recover|3.4| +|A source node matches more than one template rule.|Recover|5.5| +|A namespace Uniform Resource Identifier (URI) is declared to be an alias for multiple namespace URIs, all having the same import precedence.|Recover|7.1.1| +|The name attribute in `xsl:attribute` and `xsl:element` generated from an attribute value template is not a valid qualified name (QName).|Exception thrown|7.1.2 and 7.1.3| +|Adding an attribute to an element after child nodes have already been added to the element node.|Recover|7.1.3| +|Adding an attribute to anything other than an element node.|Recover|7.1.3| +|Instantiation of the content of the `xsl:attribute` element is not a text node.|Recover|7.1.3| +|Two attribute sets have the same import precedence and expanded name. Both have the same attribute, and there is no other attribute set containing the common attribute with the same name with higher importance.|Recover|7.1.4| +|`xsl:processing-instruction` name attribute does not yield both a no-colon name (NCName) and a Processing Instruction target.|Recover|7.3| +|Instantiating the content of `xsl:processing-instruction` creates nodes other than text nodes.|Recover|7.3| +|Results of instantiating the content of the `xsl:processing-instruction` contains the string "`?>`".|Recover|7.3| +|Results of instantiating the content of the `xsl:comment` contains the string "--", or ends with "-".|Recover|7.4| +|Results of instantiating the content of the `xsl:comment` creates nodes other than text nodes.|Recover|7.4| +|The template within a variable-binding element returns an attribute node or a namespace node.|Recover|11.2| +|There is an error retrieving the resource from the URI passed into the document function.|Exception thrown|12.1| +|The URI reference in the document function contains a fragment identifier, and there is an error processing the fragment identifier.|Exception thrown|12.1| +|There are multiple attributes with the same name that are not named `cdata-section-elements` in `xls:output`, and these attributes have the same import precedence.|Recover|16| +|The processor does not support the character encoding value given in the `encoding` attribute of the `xsl:output` element.|Recover|16.1| +|`disable-output-escaping` is used for a text node, and that text node is used to create something other than a text node in the result tree.|`disable-output-escaping` attribute is ignored|16.4| +|Converting a result tree fragment to a number or string if the result tree fragment contains a text node with output escaping enabled.|Ignored|16.4| +|Output escaping is disabled for characters that cannot be represented in the encoding that the XSLT processor is using for output.|Ignored|16.4| +|Adding a namespace node to an element after children have been added to it or after attributes have been added to it|Recover|Errata e25| +|`xsl:number` is NaN, infinite, or less than 0.5.|Recover|Errata e24| +|The second argument node-set to the document function is empty and the URI reference is relative|Recover|Errata e14| + +Sections from the errata can be found in the W3C [XSL Transformations (XSLT) Version 1.0 Specification Errata](https://www.w3.org/1999/11/REC-xslt-19991116-errata/). + +## Custom-Defined Implementation Behaviors + +There are behaviors unique to the class implementation. This section discusses the provider-specific implementation of the `xsl:sort` and optional features that are supported by the class. + +## xsl:sort + +When using a transformation to sort, the W3C XSLT 1.0 Recommendation makes some observations. They are: + +- Two XSLT processors may be conforming processors, but still may sort differently. + +- Not all XSLT processors support the same languages. + +- With regard to languages, different processors may vary on their sorting on a particular language not specified on the `xsl:sort.` + +The following table shows the sorting behavior implemented for each data type in the .NET Framework implementation of a transformation using : + +|Data type|Sorting behavior| +|---------------|----------------------| +|Text|Data is sorted using the common language runtime (CLR) String.Compare method, and the cultural locale. When the data type equals "text", sorting in the class behaves identically to the string comparison behaviors of the CLR.| +|Number|Numeric values are treated as XML Path Language (XPath) numbers and are sorted according to the details outlined in the W3C [XML Path Language (XPath) Version 1.0 Recommendation, Section 3.5](https://www.w3.org/TR/1999/REC-xpath-19991116/#numbers).| + +## Optional Features Supported + +The following table shows the features that are optional for an XSLT processor to implement and are implemented in the class. + +|Feature|Reference location|Notes| +|-------------|------------------------|-----------| +|`disable-output-escaping` attribute on `` and `` tags.|W3C XSLT 1.0 Recommendation,

Section 16.4|The `disable-output-escaping` attribute is ignored when the `xsl:text` or `xsl:value-of` elements are used in an `xsl:comment`, `xsl:processing-instruction`, or `xsl:attribute` element.

Result tree fragments that contain text and the text output that has been escaped are not supported.

The disable-output-escaping attribute is ignored when transforming to an or object.| + +## See Also + + +[XslTransform Class Implements the XSLT Processor](xsltransform-class-implements-the-xslt-processor.md) +[XSLT Transformations with the XslTransform Class](xslt-transformations-with-the-xsltransform-class.md) +[XPathNavigator in Transformations](xpathnavigator-in-transformations.md) +[XPathNodeIterator in Transformations](xpathnodeiterator-in-transformations.md) +[XPathDocument Input to XslTransform](xpathdocument-input-to-xsltransform.md) +[XmlDataDocument Input to XslTransform](xmldatadocument-input-to-xsltransform.md) +[XmlDocument Input to XslTransform](xmldocument-input-to-xsltransform.md) diff --git a/docs/standard/data/xml/result-tree-fragment-in-transformations.md b/docs/standard/data/xml/result-tree-fragment-in-transformations.md index 7e58f384bd417..09b0c2b86a219 100644 --- a/docs/standard/data/xml/result-tree-fragment-in-transformations.md +++ b/docs/standard/data/xml/result-tree-fragment-in-transformations.md @@ -7,186 +7,188 @@ author: "mairaw" ms.author: "mairaw" --- # Result Tree Fragment in Transformations + > [!NOTE] -> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](../../../../docs/standard/data/xml/using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](../../../../docs/standard/data/xml/migrating-from-the-xsltransform-class.md) for more information. - - Result tree fragments, also known as result tree fragments, are nothing more than a special type of node set. You can perform any function on them that can be performed on a node set. Or, you can also convert a result tree fragment to a node set using the `node-set()` function and subsequently use it any place that a node set can be used. - - A result tree fragment is created as a result of using an `` or `` element in a specific manner in a style sheet. The syntax for the `variable` and `parameter` elements is as follows: - -```xml - - template body - - - - template body - -``` - - For the `parameter` element, the value is assigned to the qualified name (`Qname`) in several ways. You can assign a default value to the parameter by returning content from the XML Path Language (XPath) expression in the `select` attribute, or by assigning it the contents of the template body. - - For the `variable` element, the value is also assigned in several ways. You can assign it by returning content from the XPath expression in the `select` attribute, or by assigning it the contents of the template body. - - For both the `parameter` and `variable` elements, if a value is assigned by the XPath expression, then one of the four basic XPath types will be returned: Boolean, string, number, or node set. When the value is given by using a non-empty template body, then a non-XPath data type is returned, and that will be a result tree fragment. - - When a variable is bound to a result tree fragment instead of one of the four basic XPath data types, this is the only time that an XPath query returns a type that is not one of the four XPath object types. Result tree fragments and their behavior are discussed in the World Wide Web Consortium (W3C) specification at www.w3.org/XSLT, section 11.1 Result Tree Fragments through section 11.6 Passing Parameters to Templates. Also, section 1 Introduction discusses how templates can contain elements from the XSLT namespace that return or create result tree fragments. - - A result tree fragment, in concept, behaves like a node set with nothing more than a single root node. However, the rest of the nodes returned are child nodes. To programmatically see the child nodes, copy the result tree fragment to the result tree using the `` element. When the copy-of is performed, all the child nodes are also copied to the result tree in sequence. Until a `copy` or `copy-of` is used, a result tree fragment is not part of the result tree or the output from the transformation. - - To iterate over the returned nodes of a result tree fragment, an is used. The following code sample shows how to create a result tree fragment within a style sheet by calling the function with a parameter `fragment`, which contains XML. - -```xml - - - - - - - - - function NodeFragment(XPathNavigator nav) - { - if (nav.HasSelection == false) - XPathNavigator.MoveToNext(); - return; - } - - - - - - -``` - - Here is another sample showing a variable, which is in Rich Text Format (RTF), and hence, a type of result tree fragment, that is not converted to a node set. Instead, it is passed to a script function, and the is used to navigate over the nodes. - -```xml - - - - - - Book1 - Book2 - Book3 - Book4 - - - - - - - - - - - - - - - -``` - - The result of transforming any XML with this style sheet is shown in the following output. - -## Output - -```xml -Book1 -``` - - As stated above, the `node-set` function enables you to convert a result tree fragment into a node set. The resulting node always contains a single node that is the root node of the tree. If you convert a result tree fragment to a node set, then you can use it anywhere a regular node set is used, such as in a for-each statement or in the value of a `select` attribute. The following lines of code show the fragment being converted to a node set and used as a node set: - - `` - - `` - - When a fragment is converted to a node set, you no longer use the to navigate over it. For a node set, you use the instead. - - In the following example, `$var` is a variable that is a node tree in the style sheet. The for-each statement, combined with the `node-set` function, allows the user to iterate over this tree as a node set. - -```xml - - - AL - CA - CO - WA - - - - - - -``` - - Here is another example of a variable that is in RTF, and hence of type result tree fragment, that is converted to a node set before being passed to a script function as XPathNodeIterator. - -```xml - - - - - - Book1 - Book2 - Book3 - Book4 - - - - - - - - - - - - - - -``` - - The following is the result of transforming XML with this style sheet: - -```xml -Book1Book2Book3Book4 -``` - -## See Also - - - [XSLT Transformations with the XslTransform Class](../../../../docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md) - [XslTransform Class Implements the XSLT Processor](../../../../docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md) +> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) for more information. + + Result tree fragments, also known as result tree fragments, are nothing more than a special type of node set. You can perform any function on them that can be performed on a node set. Or, you can also convert a result tree fragment to a node set using the `node-set()` function and subsequently use it any place that a node set can be used. + + A result tree fragment is created as a result of using an `` or `` element in a specific manner in a style sheet. The syntax for the `variable` and `parameter` elements is as follows: + +```xml + + template body + + + + template body + +``` + +For the `parameter` element, the value is assigned to the qualified name (`Qname`) in several ways. You can assign a default value to the parameter by returning content from the XML Path Language (XPath) expression in the `select` attribute, or by assigning it the contents of the template body. + +For the `variable` element, the value is also assigned in several ways. You can assign it by returning content from the XPath expression in the `select` attribute, or by assigning it the contents of the template body. + +For both the `parameter` and `variable` elements, if a value is assigned by the XPath expression, then one of the four basic XPath types will be returned: Boolean, string, number, or node set. When the value is given by using a non-empty template body, then a non-XPath data type is returned, and that will be a result tree fragment. + +When a variable is bound to a result tree fragment instead of one of the four basic XPath data types, this is the only time that an XPath query returns a type that is not one of the four XPath object types. Result tree fragments and their behavior are discussed in the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xslt-10/), [section 11.1 Result Tree Fragments](https://www.w3.org/TR/xslt-10/#section-Result-Tree-Fragments) through [section 11.6 Passing Parameters to Templates](https://www.w3.org/TR/xslt-10/#section-Passing-Parameters-to-Templates). Also, [section 1 Introduction](https://www.w3.org/TR/xslt-10/#section-Introduction) discusses how templates can contain elements from the XSLT namespace that return or create result tree fragments. + +A result tree fragment, in concept, behaves like a node set with nothing more than a single root node. However, the rest of the nodes returned are child nodes. To programmatically see the child nodes, copy the result tree fragment to the result tree using the `` element. When the copy-of is performed, all the child nodes are also copied to the result tree in sequence. Until a `copy` or `copy-of` is used, a result tree fragment is not part of the result tree or the output from the transformation. + +To iterate over the returned nodes of a result tree fragment, an is used. The following code sample shows how to create a result tree fragment within a style sheet by calling the function with a parameter `fragment`, which contains XML. + +```xml + + + + + + + + + function NodeFragment(XPathNavigator nav) + { + if (nav.HasSelection == false) + XPathNavigator.MoveToNext(); + return; + } + + + + + + +``` + +Here is another sample showing a variable, which is in Rich Text Format (RTF), and hence, a type of result tree fragment, that is not converted to a node set. Instead, it is passed to a script function, and the is used to navigate over the nodes. + +```xml + + + + + + Book1 + Book2 + Book3 + Book4 + + + + + + + + + + + + + + + +``` + +The result of transforming any XML with this style sheet is shown in the following output. + +## Output + +```xml +Book1 +``` + +As stated above, the `node-set` function enables you to convert a result tree fragment into a node set. The resulting node always contains a single node that is the root node of the tree. If you convert a result tree fragment to a node set, then you can use it anywhere a regular node set is used, such as in a for-each statement or in the value of a `select` attribute. The following lines of code show the fragment being converted to a node set and used as a node set: + +`` + +`` + +When a fragment is converted to a node set, you no longer use the to navigate over it. For a node set, you use the instead. + +In the following example, `$var` is a variable that is a node tree in the style sheet. The for-each statement, combined with the `node-set` function, allows the user to iterate over this tree as a node set. + +```xml + + + AL + CA + CO + WA + + + + + + +``` + +Here is another example of a variable that is in RTF, and hence of type result tree fragment, that is converted to a node set before being passed to a script function as XPathNodeIterator. + +```xml + + + + + + Book1 + Book2 + Book3 + Book4 + + + + + + + + + + + + + + +``` + +The following is the result of transforming XML with this style sheet: + +```xml +Book1Book2Book3Book4 +``` + +## See Also + + + +[XSLT Transformations with the XslTransform Class](xslt-transformations-with-the-xsltransform-class.md) +[XslTransform Class Implements the XSLT Processor](xsltransform-class-implements-the-xslt-processor.md) diff --git a/docs/standard/data/xml/style-sheet-directives-embedded-in-a-document.md b/docs/standard/data/xml/style-sheet-directives-embedded-in-a-document.md index 78dda1ae46306..fd6f68a1a3f0a 100644 --- a/docs/standard/data/xml/style-sheet-directives-embedded-in-a-document.md +++ b/docs/standard/data/xml/style-sheet-directives-embedded-in-a-document.md @@ -7,28 +7,30 @@ author: "mairaw" ms.author: "mairaw" --- # Style Sheet Directives Embedded in a Document -Occasionally, existing XML contains the style sheet directive of ``. Microsoft Internet Explorer accepts this as an alternative to the `` syntax. When the XML data contains an `` directive, as shown in the following data, attempting to load this data into the XML Document Object Model (DOM) throws an exception. - -```xml - - - - Node 1 - Node 2 - -``` - - This occurs because the `` is considered an invalid **ProcessingInstruction** to the DOM. Any **ProcessingInstruction**, according to the Namespaces in XML specification, can only be no-colon names (NCNames), as opposed to qualified names (QNames). - - From Section 6 of the Namespaces in XML specification, the effect of having the **Load** and **LoadXml** methods conform to the specification is that in a document: - -- All element types and attribute names contain either zero or one colon. - -- No entity names, ProcessingInstruction targets, or notation names contain any colons. - - With the `` containing a colon, you now violate the rule in the second bullet. - - According to the World Wide Web Consortium (W3C) Associating Style Sheets with XML documents Version 1.0 Recommendation, located at www.w3.org/TR/xml-stylesheet, the processing instruction to associate an XSLT style sheet with an XML document is ``, with a dash replacing the colon. - -## See Also - [XML Document Object Model (DOM)](../../../../docs/standard/data/xml/xml-document-object-model-dom.md) + +Occasionally, existing XML contains the style sheet directive of ``. Microsoft Internet Explorer accepts this as an alternative to the `` syntax. When the XML data contains an `` directive, as shown in the following data, attempting to load this data into the XML Document Object Model (DOM) throws an exception. + +```xml + + + + Node 1 + Node 2 + +``` + +This occurs because the `` is considered an invalid **ProcessingInstruction** to the DOM. Any **ProcessingInstruction**, according to the Namespaces in XML specification, can only be no-colon names (NCNames), as opposed to qualified names (QNames). + +From Section 6 of the Namespaces in XML specification, the effect of having the **Load** and **LoadXml** methods conform to the specification is that in a document: + +- All element types and attribute names contain either zero or one colon. + +- No entity names, ProcessingInstruction targets, or notation names contain any colons. + +With the `` containing a colon, you now violate the rule in the second bullet. + +According to the World Wide Web Consortium (W3C) [Associating Style Sheets with XML documents Version 1.0 Recommendation](https://www.w3.org/TR/xml-stylesheet/), the processing instruction to associate an XSLT style sheet with an XML document is ``, with a dash replacing the colon. + +## See Also + +[XML Document Object Model (DOM)](xml-document-object-model-dom.md) \ No newline at end of file diff --git a/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md b/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md index 7465ad1c5614b..743e93dce16af 100644 --- a/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md +++ b/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md @@ -10,148 +10,149 @@ author: "mairaw" ms.author: "mairaw" --- # XDR Validation with XmlSchemaCollection -If the XML-Data Reduced (XDR) schema you are validating against is stored in the **XmlSchemaCollection**, it is associated with the namespace URI specified when the schema was added to the collection. **XmlValidatingReader** maps the namespace URI in the XML document to the schema that corresponds to that URI in the collection. - + +If the XML-Data Reduced (XDR) schema you are validating against is stored in the **XmlSchemaCollection**, it is associated with the namespace URI specified when the schema was added to the collection. **XmlValidatingReader** maps the namespace URI in the XML document to the schema that corresponds to that URI in the collection. + > [!IMPORTANT] -> The class is now obsolete and has been replaced with the class. For more information about the class see, [XmlSchemaSet for Schema Compilation](../../../../docs/standard/data/xml/xmlschemaset-for-schema-compilation.md). - - For example, if the root element of the XML document is ``, when the schema is added to the **XmlSchemaCollection** it references the same namespace, as follows: - -``` -xsc.Add("urn:newbooks-schema", "newbooks.xdr") -``` - - The following code example creates an **XmlValidatingReader** that takes an **XmlTextReader** and adds an XDR schema, HeadCount.xdr, to the **XmlSchemaCollection**. - -```vb -Imports System -Imports System.IO -Imports System.Xml -Imports System.Xml.Schema - -Namespace ValidationSample - - Class Sample - - Public Shared Sub Main() - Dim tr As New XmlTextReader("HeadCount.xml") - Dim vr As New XmlValidatingReader(tr) - - vr.Schemas.Add("xdrHeadCount", "HeadCount.xdr") - vr.ValidationType = ValidationType.XDR - AddHandler vr.ValidationEventHandler, AddressOf ValidationHandler - - While vr.Read() - PrintTypeInfo(vr) - If vr.NodeType = XmlNodeType.Element Then - While vr.MoveToNextAttribute() - PrintTypeInfo(vr) - End While - End If - End While - Console.WriteLine("Validation finished") - End Sub - ' Main - - Public Shared Sub PrintTypeInfo(vr As XmlValidatingReader) - If Not (vr.SchemaType Is Nothing) Then - If TypeOf vr.SchemaType Is XmlSchemaDatatype Or TypeOf vr.SchemaType Is XmlSchemaSimpleType Then - Dim value As Object = vr.ReadTypedValue() - Console.WriteLine("{0}({1},{2}):{3}", vr.NodeType, vr.Name, value.GetType().Name, value) - End If - End If - End Sub - ' PrintTypeInfo - - Public Shared Sub ValidationHandler(sender As Object, args As ValidationEventArgs) - Console.WriteLine("***Validation error") - Console.WriteLine("Severity:{0}", args.Severity) - Console.WriteLine("Message:{0}", args.Message) - End Sub - ' ValidationHandler - End Class - ' Sample -End Namespace -' ValidationSample -``` - -```csharp -using System; -using System.IO; -using System.Xml; -using System.Xml.Schema; - -namespace ValidationSample -{ - class Sample - { - public static void Main() - { - XmlTextReader tr = new XmlTextReader("HeadCount.xml"); - XmlValidatingReader vr = new XmlValidatingReader(tr); - - vr.Schemas.Add("xdrHeadCount", "HeadCount.xdr"); - vr.ValidationType = ValidationType.XDR; - vr.ValidationEventHandler += new ValidationEventHandler (ValidationHandler); - - while(vr.Read()) - { - PrintTypeInfo(vr); - if(vr.NodeType == XmlNodeType.Element) - { - while(vr.MoveToNextAttribute()) - PrintTypeInfo(vr); - } - } - Console.WriteLine("Validation finished"); - } - - public static void PrintTypeInfo(XmlValidatingReader vr) - { - if(vr.SchemaType != null) - { - if(vr.SchemaType is XmlSchemaDatatype || vr.SchemaType is XmlSchemaSimpleType) - { - object value = vr.ReadTypedValue(); - Console.WriteLine("{0}({1},{2}):{3}", vr.NodeType, vr.Name, value.GetType().Name, value); - } - } - } - - public static void ValidationHandler(object sender, ValidationEventArgs args) - { - Console.WriteLine("***Validation error"); - Console.WriteLine("\tSeverity:{0}", args.Severity); - Console.WriteLine("\tMessage:{0}", args.Message); - } - } -} -``` - - The following outlines the contents of the input file, HeadCount.xml, to be validated. - -```xml - - - Waldo Pepper - Red Pepper - -``` - - The following outlines the contents of the XDR schema file, HeadCount.xdr, to be validated against. - -```xml - - - - - - - - -``` - -## See Also - - `System.Xml.XmlValidatingReader.Settings` - [XmlSchemaCollection Schema Compilation](../../../../docs/standard/data/xml/xmlschemacollection-schema-compilation.md) +> The class is now obsolete and has been replaced with the class. For more information about the class see, [XmlSchemaSet for Schema Compilation](xmlschemaset-for-schema-compilation.md). + +For example, if the root element of the XML document is ``, when the schema is added to the **XmlSchemaCollection** it references the same namespace, as follows: + +``` +xsc.Add("urn:newbooks-schema", "newbooks.xdr") +``` + +The following code example creates an **XmlValidatingReader** that takes an **XmlTextReader** and adds an XDR schema, HeadCount.xdr, to the **XmlSchemaCollection**. + +```vb +Imports System +Imports System.IO +Imports System.Xml +Imports System.Xml.Schema + +Namespace ValidationSample + + Class Sample + + Public Shared Sub Main() + Dim tr As New XmlTextReader("HeadCount.xml") + Dim vr As New XmlValidatingReader(tr) + + vr.Schemas.Add("xdrHeadCount", "HeadCount.xdr") + vr.ValidationType = ValidationType.XDR + AddHandler vr.ValidationEventHandler, AddressOf ValidationHandler + + While vr.Read() + PrintTypeInfo(vr) + If vr.NodeType = XmlNodeType.Element Then + While vr.MoveToNextAttribute() + PrintTypeInfo(vr) + End While + End If + End While + Console.WriteLine("Validation finished") + End Sub + ' Main + + Public Shared Sub PrintTypeInfo(vr As XmlValidatingReader) + If Not (vr.SchemaType Is Nothing) Then + If TypeOf vr.SchemaType Is XmlSchemaDatatype Or TypeOf vr.SchemaType Is XmlSchemaSimpleType Then + Dim value As Object = vr.ReadTypedValue() + Console.WriteLine("{0}({1},{2}):{3}", vr.NodeType, vr.Name, value.GetType().Name, value) + End If + End If + End Sub + ' PrintTypeInfo + + Public Shared Sub ValidationHandler(sender As Object, args As ValidationEventArgs) + Console.WriteLine("***Validation error") + Console.WriteLine("Severity:{0}", args.Severity) + Console.WriteLine("Message:{0}", args.Message) + End Sub + ' ValidationHandler + End Class + ' Sample +End Namespace +' ValidationSample +``` + +```csharp +using System; +using System.IO; +using System.Xml; +using System.Xml.Schema; + +namespace ValidationSample +{ + class Sample + { + public static void Main() + { + XmlTextReader tr = new XmlTextReader("HeadCount.xml"); + XmlValidatingReader vr = new XmlValidatingReader(tr); + + vr.Schemas.Add("xdrHeadCount", "HeadCount.xdr"); + vr.ValidationType = ValidationType.XDR; + vr.ValidationEventHandler += new ValidationEventHandler (ValidationHandler); + + while(vr.Read()) + { + PrintTypeInfo(vr); + if(vr.NodeType == XmlNodeType.Element) + { + while(vr.MoveToNextAttribute()) + PrintTypeInfo(vr); + } + } + Console.WriteLine("Validation finished"); + } + + public static void PrintTypeInfo(XmlValidatingReader vr) + { + if(vr.SchemaType != null) + { + if(vr.SchemaType is XmlSchemaDatatype || vr.SchemaType is XmlSchemaSimpleType) + { + object value = vr.ReadTypedValue(); + Console.WriteLine("{0}({1},{2}):{3}", vr.NodeType, vr.Name, value.GetType().Name, value); + } + } + } + + public static void ValidationHandler(object sender, ValidationEventArgs args) + { + Console.WriteLine("***Validation error"); + Console.WriteLine("\tSeverity:{0}", args.Severity); + Console.WriteLine("\tMessage:{0}", args.Message); + } + } +} +``` + +The following outlines the contents of the input file, *HeadCount.xml*, to be validated: + +```xml + + + Waldo Pepper + Red Pepper + +``` + +The following outlines the contents of the XDR schema file, *HeadCount.xdr*, to be validated against: + +```xml + + + + + + + + +``` + +## See Also + + +[XmlSchemaCollection Schema Compilation](xmlschemacollection-schema-compilation.md) \ No newline at end of file diff --git a/docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md b/docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md index 6cf3dcc9ccd86..b15095a3f2dff 100644 --- a/docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md +++ b/docs/standard/data/xml/xslt-transformations-with-the-xsltransform-class.md @@ -10,89 +10,93 @@ author: "mairaw" ms.author: "mairaw" --- # XSLT Transformations with the XslTransform Class + > [!NOTE] -> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](../../../../docs/standard/data/xml/using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](../../../../docs/standard/data/xml/migrating-from-the-xsltransform-class.md) for more information. - - The goal of the XSLT is to transform the content of a source XML document into another document that is different in format or structure (for example, to transform XML into HTML for use on a Web site or to transform it into a document that contains only the fields required by an application). This transformation process is specified by the World Wide Web Consortium (W3C) XSLT version 1.0 recommendation located at www.w3.org/TR/xslt. In the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)], the class, found in the namespace, is the XSLT processor that implements the functionality of this specification. There are a small number of features that have not been implemented from the W3C XSLT 1.0 recommendation, listed in [Outputs from an XslTransform](../../../../docs/standard/data/xml/outputs-from-an-xsltransform.md). The following figure shows the transformation architecture of the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)]. - -## Overview - ![XSLT Transformation Architecture](../../../../docs/standard/data/xml/media/xslttransformationswithxsltransformclass.gif "xsltTransformationsWithXslTransformClass") -Transformation Architecture - - The XSLT recommendation uses XML Path Language (XPath) to select parts of an XML document, where XPath is a query language used to navigate nodes of a document tree. As shown in the diagram, the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] implementation of XPath is used to select parts of XML stored in several classes, such as an , an , and an . An is an optimized XSLT data store, and when used with , it provides XSLT transformations with good performance. - - The following table list commonly uses classes when working with and XPath and their function. - -|Class or Interface|Function| -|------------------------|--------------| -||It is an API that provides a cursor style model for navigating over a store, along with XPath query support. It does not provide editing of the underlying store. For editing, use the class.| -||It is an interface that provides a `CreateNavigator` method to an for the store.| -||It enables editing of this document. It implements , allowing document-editing scenarios where XSLT transformations are subsequently required. For more information, see [XmlDocument Input to XslTransform](../../../../docs/standard/data/xml/xmldocument-input-to-xsltransform.md).| -||It is derived from the . It bridges the relational and XML worlds by using a to optimize storage of structured data within the XML document according to specified mappings on the . It implements , allowing scenarios where XSLT transformations can be performed over relational data retrieved from a database. For more information, see [XML Integration with Relational Data and ADO.NET](../../../../docs/standard/data/xml/xml-integration-with-relational-data-and-adonet.md).| -||This class is optimized for processing and XPath queries, and it provides a read-only high performance cache. It implements and is the preferred store to use for XSLT transformations.| -||It provides navigation over XPath node sets. All XPath selection methods on the return an . Multiple objects can be created over the same store, each representing a selected set of nodes.| - -## MSXML XSLT Extensions - The `msxsl:script` and `msxsl:node-set` functions are the only Microsoft XML Core Services (MSXML) XSLT extensions supported by the class. - -## Example - The following code example loads an XSLT style sheet, reads a file called mydata.xml into an , and performs a transformation on the data on a fictitious file called myStyleSheet.xsl, sending the formatted output to the console. - -```vb -Imports System -Imports System.IO -Imports System.Xml -Imports System.Xml.XPath -Imports System.Xml.Xsl - -Public Class Sample - Private filename As [String] = "mydata.xml" - Private stylesheet As [String] = "myStyleSheet.xsl" - - Public Shared Sub Main() - Dim xslt As New XslTransform() - xslt.Load(stylesheet) - Dim xpathdocument As New XPathDocument(filename) - Dim writer As New XmlTextWriter(Console.Out) - writer.Formatting = Formatting.Indented - - xslt.Transform(xpathdocument, Nothing, writer, Nothing) - End Sub 'Main -End Class 'Sample -``` - -```csharp -using System; -using System.IO; -using System.Xml; -using System.Xml.XPath; -using System.Xml.Xsl; - -public class Sample -{ - private const String filename = "mydata.xml"; - private const String stylesheet = "myStyleSheet.xsl"; - - public static void Main() - { - XslTransform xslt = new XslTransform(); - xslt.Load(stylesheet); - XPathDocument xpathdocument = new - XPathDocument(filename); - XmlTextWriter writer = new XmlTextWriter(Console.Out); - writer.Formatting=Formatting.Indented; - - xslt.Transform(xpathdocument, null, writer, null); - } -} -``` - -## See Also - - [XslTransform Class Implements the XSLT Processor](../../../../docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md) - [Implementation of Discretionary Behaviors in the XslTransform Class](../../../../docs/standard/data/xml/implementation-of-discretionary-behaviors-in-the-xsltransform-class.md) - [XPathNavigator in Transformations](../../../../docs/standard/data/xml/xpathnavigator-in-transformations.md) - [XPathNodeIterator in Transformations](../../../../docs/standard/data/xml/xpathnodeiterator-in-transformations.md) - [XPathDocument Input to XslTransform](../../../../docs/standard/data/xml/xpathdocument-input-to-xsltransform.md) - [XmlDataDocument Input to XslTransform](../../../../docs/standard/data/xml/xmldatadocument-input-to-xsltransform.md) - [XmlDocument Input to XslTransform](../../../../docs/standard/data/xml/xmldocument-input-to-xsltransform.md) +> The class is obsolete in the [!INCLUDE[dnprdnext](../../../../includes/dnprdnext-md.md)]. You can perform Extensible Stylesheet Language for Transformations (XSLT) transformations using the class. See [Using the XslCompiledTransform Class](using-the-xslcompiledtransform-class.md) and [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) for more information. + +The goal of the XSLT is to transform the content of a source XML document into another document that is different in format or structure (for example, to transform XML into HTML for use on a Web site or to transform it into a document that contains only the fields required by an application). This transformation process is specified by the World Wide Web Consortium (W3C)[XSLT version 1.0 recommendation](https://www.w3.org/TR/1999/REC-xslt-19991116). In the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)], the class, found in the namespace, is the XSLT processor that implements the functionality of this specification. There are a small number of features that have not been implemented from the W3C XSLT 1.0 recommendation, listed in [Outputs from an XslTransform](outputs-from-an-xsltransform.md). The following figure shows the transformation architecture of the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)]. + +## Overview + +![XSLT Transformation Architecture](media/xslttransformationswithxsltransformclass.gif "xsltTransformationsWithXslTransformClass") +Transformation Architecture + +The XSLT recommendation uses XML Path Language (XPath) to select parts of an XML document, where XPath is a query language used to navigate nodes of a document tree. As shown in the diagram, the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] implementation of XPath is used to select parts of XML stored in several classes, such as an , an , and an . An is an optimized XSLT data store, and when used with , it provides XSLT transformations with good performance. + +The following table list commonly uses classes when working with and XPath and their function. + +|Class or Interface|Function| +|------------------------|--------------| +||It is an API that provides a cursor style model for navigating over a store, along with XPath query support. It does not provide editing of the underlying store. For editing, use the class.| +||It is an interface that provides a `CreateNavigator` method to an for the store.| +||It enables editing of this document. It implements , allowing document-editing scenarios where XSLT transformations are subsequently required. For more information, see [XmlDocument Input to XslTransform](xmldocument-input-to-xsltransform.md).| +||It is derived from the . It bridges the relational and XML worlds by using a to optimize storage of structured data within the XML document according to specified mappings on the . It implements , allowing scenarios where XSLT transformations can be performed over relational data retrieved from a database. For more information, see [XML Integration with Relational Data and ADO.NET](xml-integration-with-relational-data-and-adonet.md).| +||This class is optimized for processing and XPath queries, and it provides a read-only high performance cache. It implements and is the preferred store to use for XSLT transformations.| +||It provides navigation over XPath node sets. All XPath selection methods on the return an . Multiple objects can be created over the same store, each representing a selected set of nodes.| + +## MSXML XSLT Extensions + +The `msxsl:script` and `msxsl:node-set` functions are the only Microsoft XML Core Services (MSXML) XSLT extensions supported by the class. + +## Example + +The following code example loads an XSLT style sheet, reads a file called mydata.xml into an , and performs a transformation on the data on a fictitious file called myStyleSheet.xsl, sending the formatted output to the console. + +```vb +Imports System +Imports System.IO +Imports System.Xml +Imports System.Xml.XPath +Imports System.Xml.Xsl + +Public Class Sample + Private filename As [String] = "mydata.xml" + Private stylesheet As [String] = "myStyleSheet.xsl" + + Public Shared Sub Main() + Dim xslt As New XslTransform() + xslt.Load(stylesheet) + Dim xpathdocument As New XPathDocument(filename) + Dim writer As New XmlTextWriter(Console.Out) + writer.Formatting = Formatting.Indented + + xslt.Transform(xpathdocument, Nothing, writer, Nothing) + End Sub 'Main +End Class 'Sample +``` + +```csharp +using System; +using System.IO; +using System.Xml; +using System.Xml.XPath; +using System.Xml.Xsl; + +public class Sample +{ + private const String filename = "mydata.xml"; + private const String stylesheet = "myStyleSheet.xsl"; + + public static void Main() + { + XslTransform xslt = new XslTransform(); + xslt.Load(stylesheet); + XPathDocument xpathdocument = new XPathDocument(filename); + XmlTextWriter writer = new XmlTextWriter(Console.Out); + writer.Formatting = Formatting.Indented; + + xslt.Transform(xpathdocument, null, writer, null); + } +} +``` + +## See Also + + +[XslTransform Class Implements the XSLT Processor](xsltransform-class-implements-the-xslt-processor.md) +[Implementation of Discretionary Behaviors in the XslTransform Class](implementation-of-discretionary-behaviors-in-the-xsltransform-class.md) +[XPathNavigator in Transformations](xpathnavigator-in-transformations.md) +[XPathNodeIterator in Transformations](xpathnodeiterator-in-transformations.md) +[XPathDocument Input to XslTransform](xpathdocument-input-to-xsltransform.md) +[XmlDataDocument Input to XslTransform](xmldatadocument-input-to-xsltransform.md) +[XmlDocument Input to XslTransform](xmldocument-input-to-xsltransform.md) \ No newline at end of file diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index 6b58cb36b0a9d..0ab145a202d09 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -34,21 +34,21 @@ Large objects belong to generation 2 because they are collected only during a ge Generations provide a logical view of the GC heap. Physically, objects live in managed heap segments. A *managed heap segment* is a chunk of memory that the GC reserves from the OS by calling the [VirtualAlloc function](https://msdn.microsoft.com/library/windows/desktop/aa366887(v=vs.85).aspx) on behalf of managed code. When the CLR is loaded, the GC allocates two initial heap segments: one for small objects (the Small Object Heap, or SOH), and one for large objects (the Large Object Heap). The allocation requests are then satisfied by putting managed objects on these managed heap segments. If the object is less than 85,000 bytes, it is put on the segment for the SOH; otherwise, it is put on an LOH segment. Segments are committed (in smaller chunks) as more and more objects are allocated onto them. -For the SOH, objects that survive a GC are promoted to the next generation. Objects that survive a generation 0 collection are now considered generation 1 objects, and so on. However, objects that survive the oldest generation are still considered to be in the oldest generation. In other words, survivors from generation 2 are generation 2 objects; and survivors from the LOH are LOH objects (which are collected with gen2). +For the SOH, objects that survive a GC are promoted to the next generation. Objects that survive a generation 0 collection are now considered generation 1 objects, and so on. However, objects that survive the oldest generation are still considered to be in the oldest generation. In other words, survivors from generation 2 are generation 2 objects; and survivors from the LOH are LOH objects (which are collected with gen2). User code can only allocate in generation 0 (small objects) or the LOH (large objects). Only the GC can “allocate” objects in generation 1 (by promoting survivors from generation 0) and generation 2 (by promoting survivors from generations 1 and 2). When a garbage collection is triggered, the GC traces through the live objects and compacts them. But because compaction is expensive, the GC *sweeps* the LOH; it makes a free list out of dead objects that can be reused later to satisfy large object allocation requests. Adjacent dead objects are made into one free object. -.NET Core and .NET Framework (starting with .NET Framework 4.5.1) include the property that allows users to specify that the LOH should be compacted during the next full blocking GC. And in the future, .NET may decide to compact the LOH automatically. This means that, if you allocate large objects and want to make sure that they don’t move, you should still pin them. +.NET Core and .NET Framework (starting with .NET Framework 4.5.1) include the property that allows users to specify that the LOH should be compacted during the next full blocking GC. And in the future, .NET may decide to compact the LOH automatically. This means that, if you allocate large objects and want to make sure that they don’t move, you should still pin them. Figure 1 illustrates a scenario where the GC forms generation 1 after the first generation 0 GC where `Obj1` and `Obj3` are dead, and it forms generation 2 after the first generation 1 GC where `Obj2` and `Obj5` are dead. Note that this and the following figures are only for illustration purposes; they contain very few objects to better show what happens on the heap. In reality, many more objects are typically involved in a GC. -![Figure 1: A gen 0 GC and a gen 1 GC](media/loh/loh-figure-1.jpg) +![Figure 1: A gen 0 GC and a gen 1 GC](media/loh/loh-figure-1.jpg) Figure 1: A generation 0 and a generation 1 GC. Figure 2 shows that after a generation 2 GC which saw that `Obj1` and `Obj2` are dead, the GC forms contiguous free space out of memory that used to be occupied by `Obj1` and `Obj2`, which then was used to satisfy an allocation request for `Obj4`. The space after the last object, `Obj3`, to end of the segment can also be used to satisfy allocation requests. - + ![Figure 2: After a gen 2 GC](media/loh/loh-figure-2.jpg) Figure 2: After a generation 2 GC @@ -57,7 +57,7 @@ If there isn't enough free space to accommodate the large object allocation requ During a generation 1 or generation 2 GC, the garbage collector releases segments that have no live objects on them back to the OS by calling the [VirtualFree function](https://msdn.microsoft.com/library/windows/desktop/aa366892(v=vs.85).aspx). Space after the last live object to the end of the segment is decommitted (except on the ephemeral segment where gen0/gen1 live, where the garbage collector does keep some committed because your application will be allocating in it right away). And the free spaces remain committed though they are reset, meaning that the OS doesn’t need to write data in them back to disk. Since the LOH is only collected during generation 2 GCs, the LOH segment can only be freed during such a GC. Figure 3 illustrates a scenario where the garbage collector releases one segment (segment 2) back to the OS and decommits more space on the remaining segments. If it needs to use the decommitted space at the end of the segment to satisfy large object allocation requests, it commits the memory again. (For an explanation of commit/decommit, see the documentation for [VirtualAlloc](https://msdn.microsoft.com/library/windows/desktop/aa366887(v=vs.85).aspx). - + ![Figure 3: LOH after a gen 2 GC](media/loh/loh-figure-3.jpg) Figure 3: The LOH after a generation 2 GC @@ -67,17 +67,17 @@ In general, a GC occurs when one of the following following 3 conditions happens - Allocation exceeds the generation 0 or large object threshold. - The threshold is a property of a generation. A threshold for a generation is set when the garbage collector allocates objects into it. When the threshold is exceeded, a GC is triggered on that generation. When you allocate small or large objects, you consume generation 0 and the LOH’s thresholds, respectively. When the garbage collector allocates into generation 1 and 2, it consumes their thresholds. These thresholds are dynamically tuned as the program runs. + The threshold is a property of a generation. A threshold for a generation is set when the garbage collector allocates objects into it. When the threshold is exceeded, a GC is triggered on that generation. When you allocate small or large objects, you consume generation 0 and the LOH’s thresholds, respectively. When the garbage collector allocates into generation 1 and 2, it consumes their thresholds. These thresholds are dynamically tuned as the program runs. - This is the typical case; most GCs happen because of allocations on the managed heap. + This is the typical case; most GCs happen because of allocations on the managed heap. - The method is called. - If the parameterless method is called or another overload is passed as an argument, the LOH is collected along with the rest of the managed heap. + If the parameterless method is called or another overload is passed as an argument, the LOH is collected along with the rest of the managed heap. - The system is in low memory situation. - This occurs when the garbage collector receives a high memory notification from the OS. If the garbage collector thinks that doing a generation 2 GC will be productive, it triggers one. + This occurs when the garbage collector receives a high memory notification from the OS. If the garbage collector thinks that doing a generation 2 GC will be productive, it triggers one. ## LOH Performance Implications @@ -85,41 +85,41 @@ Allocations on the large object heap impact performance in the following ways. - Allocation cost. - The CLR makes the guarantee that the memory for every new object it gives out is cleared. This means the allocation cost of a large object is completely dominated by memory clearing (unless it triggers a GC). If it takes 2 cycles to clear one byte, it takes 170,000 cycles to clear the smallest large object. Clearing the memmory of a 16MB object on a 2GHz machine takes approximately 16ms. That's a rather large cost. + The CLR makes the guarantee that the memory for every new object it gives out is cleared. This means the allocation cost of a large object is completely dominated by memory clearing (unless it triggers a GC). If it takes 2 cycles to clear one byte, it takes 170,000 cycles to clear the smallest large object. Clearing the memmory of a 16MB object on a 2GHz machine takes approximately 16ms. That's a rather large cost. - Collection cost. - Because the LOH and generation 2 are collected together, if either one's threshold is exceeded, a generation 2 collection is triggered. If a generation 2 collection is triggered because of the LOH, generation 2 won't necessarily be much smaller after the GC. If there's not much data on generation 2, this has minimal impact. But if generation 2 is large, it can cause performance problems if many generation 2 GCs are triggered. If many large objects are allocated on a very temporary basis and you have a large SOH, you could be spending too much time doing GCs. In addition, the allocation cost can really add up if you keep allocating and letting go of really large objects. + Because the LOH and generation 2 are collected together, if either one's threshold is exceeded, a generation 2 collection is triggered. If a generation 2 collection is triggered because of the LOH, generation 2 won't necessarily be much smaller after the GC. If there's not much data on generation 2, this has minimal impact. But if generation 2 is large, it can cause performance problems if many generation 2 GCs are triggered. If many large objects are allocated on a very temporary basis and you have a large SOH, you could be spending too much time doing GCs. In addition, the allocation cost can really add up if you keep allocating and letting go of really large objects. - Array elements with reference types. - Very large objects on the LOH are usually arrays (it's very rare to have an instance object that's really large). If the elements of an array are reference-rich, it incurs a cost that is not present if the elements are not reference-rich. If the element doesn’t contain any references, the garbage collector doesn’t need to go through the array at all. For example, if you use an array to store nodes in a binary tree, one way to implement it is to refer to a node’s right and left node by the actual nodes: + Very large objects on the LOH are usually arrays (it's very rare to have an instance object that's really large). If the elements of an array are reference-rich, it incurs a cost that is not present if the elements are not reference-rich. If the element doesn’t contain any references, the garbage collector doesn’t need to go through the array at all. For example, if you use an array to store nodes in a binary tree, one way to implement it is to refer to a node’s right and left node by the actual nodes: - ```csharp - class Node - { - Data d; - Node left; - Node right; - }; + ```csharp + class Node + { + Data d; + Node left; + Node right; + }; - Node[] binary_tr = new Node [num_nodes]; - ``` + Node[] binary_tr = new Node [num_nodes]; + ``` - If `num_nodes` is large, the garbage collector needs to go through at least two references per element. An alternative approach is to store the index of the right and the left nodes: + If `num_nodes` is large, the garbage collector needs to go through at least two references per element. An alternative approach is to store the index of the right and the left nodes: - ```csharp - class Node - { - Data d; - uint left_index; - uint right_index; - } ; - ``` + ```csharp + class Node + { + Data d; + uint left_index; + uint right_index; + } ; + ``` - Instead of referring the left node’s data as `left.d`, you refer to it as `binary_tr[left_index].d`. And the garbage collector doesn’t need to look at any references for the left and right node. + Instead of referring the left node’s data as `left.d`, you refer to it as `binary_tr[left_index].d`. And the garbage collector doesn’t need to look at any references for the left and right node. -Out of the three factors, the first two are usually more significant than the third. Because of this, we recommend that you allocate a pool of large objects that you reuse instead of allocating temporary ones. +Out of the three factors, the first two are usually more significant than the third. Because of this, we recommend that you allocate a pool of large objects that you reuse instead of allocating temporary ones. ## Collecting performance data for the LOH @@ -127,7 +127,7 @@ Before you collect performance data for a specific area, you should already have 1. Found evidence that you should be looking at this area. -1. Exhausted other areas that you know of without finding anything that could explain the performance problem you saw. +2. Exhausted other areas that you know of without finding anything that could explain the performance problem you saw. See the blog [Understand the problem before you try to find a solution](https://blogs.msdn.microsoft.com/maoni/2006/09/01/understand-the-problem-before-you-try-to-find-a-solution/) for more information on the fundamentals of memory and the CPU. @@ -143,7 +143,7 @@ You can use the following tools to collect data on LOH performance: These performance counters are usually a good first step in investigating performance issues (although we recommend that you use [ETW events](#etw)). You configure Performance Monitor by adding the counters that you want, as Figure 4 shows. The ones that are relevant for the LOH are: -- **\# Gen 2 Collections** +- **Gen 2 Collections** Displays the number of times generation 2 GCs have occurred since the process started. The counter is incremented at the end of a generation 2 collection (also called a full garbage collection). This counter displays the last observed value. @@ -153,7 +153,7 @@ These performance counters are usually a good first step in investigating perfor A common way to look at performance counters is with Performance Monitor (perfmon.exe). Use “Add Counters” to add the interesting counter for processes that you care about. You can save the performance counter data to a log file, as Figure 4 shows. -![Figure 4: Adding performance counters.](media/loh/perfcounter.png) +![Figure 4: Adding performance counters.](media/loh/perfcounter.png) Figure 4: The LOH after a generation 2 GC Performance counters can also be queried programmatically. Many people collect them this way as part of their routine testing process. When they spot counters with values that are out of the ordinary, they use other means to get more detailed data to help with the investigation. @@ -165,13 +165,13 @@ Performance counters can also be queried programmatically. Many people collect t The garbage collector provides a rich set of ETW events to help you understand what the heap is doing and why. The following blog posts show how to collect and understand GC events with ETW: -- [GC ETW Events - 1 ](http://blogs.msdn.com/b/maoni/archive/2014/12/22/gc-etw-events.aspx) +- [GC ETW Events - 1](https://blogs.msdn.microsoft.com/maoni/2014/12/22/gc-etw-events-1/) -- [GC ETW Events - 2](http://blogs.msdn.com/b/maoni/archive/2014/12/25/gc-etw-events-2.aspx) +- [GC ETW Events - 2](https://blogs.msdn.microsoft.com/maoni/2014/12/25/gc-etw-events-2/) -- [GC ETW Events - 3](http://blogs.msdn.com/b/maoni/archive/2014/12/25/gc-etw-events-3.aspx) +- [GC ETW Events - 3](https://blogs.msdn.microsoft.com/maoni/2014/12/25/gc-etw-events-3/) -- [GC ETW Events - 4](http://blogs.msdn.com/b/maoni/archive/2014/12/30/gc-etw-events-4.aspx) +- [GC ETW Events - 4](https://blogs.msdn.microsoft.com/maoni/2014/12/30/gc-etw-events-4/) To identify excessive generation 2 GCs caused by temporary LOH allocations, look at the Trigger Reason column for GCs. For a simple test that only allocates temporary large objects, you can collect information on ETW events with the following [PerfView](https://www.microsoft.com/download/details.aspx?id=28567) command line: @@ -180,7 +180,7 @@ perfview /GCCollectOnly /AcceptEULA /nogui collect ``` The result is something like this: - + ![Figure 5: Examining ETW events using PerfView](media/loh/perfview.png) Figure 5: ETW events shown using PerfView @@ -193,15 +193,15 @@ perfview /GCOnly /AcceptEULA /nogui collect ``` collects an AllocationTick event which is fired approximately every 100k worth of allocations. In other words, an event is fired each time a large object is allocated. You can then look at one of the GC Heap Alloc views which show you the callstacks that allocated large objects: - + ![Figure 6: A GC Heap Alloc view](media/loh/perfview2.png) Figure 6: A GC Heap Alloc view - + As you can see, this is a very simple test that just allocates large objects from its `Main` method. ### A debugger -If all you have is a memory dump and you need to look at what objects are actually on the LOH, you can use the [SoS debugger extension](http://msdn2.microsoft.com/ms404370.aspx) provided by .NET. +If all you have is a memory dump and you need to look at what objects are actually on the LOH, you can use the [SoS debugger extension](http://msdn2.microsoft.com/ms404370.aspx) provided by .NET. > [!NOTE] > The debugging commands mentioned in this section are applicable to the [Windows Debuggers](http://www.microsoft.com/whdc/devtools/debugging/default.mspx). @@ -237,7 +237,7 @@ MT Count TotalSize Class Name Total 133 objects ``` -The LOH heap size is (16,754,224 + 16,699,288 + 16,284,504) = 49,738,016 bytes. Between addresses 023e1000 and 033db630, 8,008,736 bytes are occupied by an array of objects, 6,663,696 bytes are occupied by an array of objects, and 2,081,792 bytes are occupied by free space. +The LOH heap size is (16,754,224 + 16,699,288 + 16,284,504) = 49,738,016 bytes. Between addresses 023e1000 and 033db630, 8,008,736 bytes are occupied by an array of objects, 6,663,696 bytes are occupied by an array of objects, and 2,081,792 bytes are occupied by free space. Sometimes, the debugger shows that the total size of the LOH is less than 85,000 bytes. This happens because the runtime itself uses the LOH to allocate some objects that are smaller than a large object. @@ -311,4 +311,4 @@ CLR 2.0 added a feature called *VM Hoarding* that can be useful for scenarious w VM hoarding is also useful for applications that want to hold onto the segments that they already acquired, such as some server apps that are the dominant apps running on the system, to avoid out of memory exceptions. -We strongly recommend that you carefully test your application when you use this feature to ensure your application has fairly stable memory usage. +We strongly recommend that you carefully test your application when you use this feature to ensure your application has fairly stable memory usage. \ No newline at end of file diff --git a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md index 1f4da86e6a529..ee773ddac585d 100644 --- a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md +++ b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md @@ -10,70 +10,72 @@ author: "mairaw" ms.author: "mairaw" --- # How to: Convert Between .NET Framework Streams and Windows Runtime Streams -The .NET Framework for Windows Store apps is a subset of the full .NET Framework. Because of security and other requirements for Windows Store apps, you cannot use the full set of .NET Framework APIs to open and read files. For more information, see [.NET for Windows Store apps overview](http://msdn.microsoft.com/library/windows/apps/br230302.aspx). However, you may want to use .NET Framework APIs for other stream manipulation operations. To manipulate these streams, you may find it necessary to convert between a .NET Framework stream type such as or , and a Windows Runtime stream such as [IInputStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.iinputstream.aspx), [IOutputStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.ioutputstream.aspx), or [IRandomAccessStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.irandomaccessstream.aspx). - - The `System.IO.WindowsRuntimeStreamExtensions` class contains methods that make these conversions easy. However, there are underlying differences between streams in the .NET Framework and the Windows Runtime that will affect the results of using these methods. The details are described in the following sections. - - -## Converting from a Windows Runtime stream to a .NET Framework stream - You can convert from a Windows Runtime stream to a .NET Framework stream by using one of the following `System.IO.WindowsRuntimeStreamExtensions` methods: - - `System.IO.WindowsRuntimeStreamExtensions.AsStream` - Converts a random-access stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. - - `System.IO.WindowsRuntimeStreamExtensions.AsStreamForWrite` - Converts an output stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. - - `System.IO.WindowsRuntimeStreamExtensions.AsStreamForRead` - Converts an input stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. - - The Windows Runtime offers stream types that support reading only, writing only or reading and writing, and these capabilities are maintained when you convert a Windows Runtime stream to a .NET Framework stream. Furthermore, if you convert a Windows Runtime stream to a .NET Framework stream and back, you get the original Windows Runtime instance back. It’s best practice to use the conversion method that matches the capabilities of the Windows Runtime stream you would like to convert. However, since [IRandomAccessStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.irandomaccessstream.aspx) is readable and writeable (it implements both [IOutputStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.ioutputstream.aspx) and [IInputStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.iinputstream.aspx)), you can use any of the conversion methods and the capabilities of the original stream are maintained. For example, using `System.IO.WindowsRuntimeStreamExtensions.AsStreamForRead` to convert an [IRandomAccessStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.irandomaccessstream.aspx) will not limit the converted .NET Framework stream to being readable only; it will also be writable. - -#### To convert from a Windows Runtime random-access stream to a .NET Framework stream - -- Use the `System.IO.WindowsRuntimeStreamExtensions.AsStream` method. - - The following code example shows how to prompt the user to select a file, open it with Windows Runtime APIs, and then convert it to a .NET Framework stream, which is read and output to a text block. In this scenario, you would typically manipulate the stream with .NET Framework APIs before outputting the results. - - To run this example, you must create a Windows Store XAML app that contains a text block named `TextBlock1` and a button named `Button1`. The button click event must be associated with the `button1_Click` method shown in the example. - - [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#imports)] - [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#imports)] - [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#1)] - [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#1)] - - -## Converting from a .NET Framework stream to a Windows Runtime stream - You can convert from a .NET Framework stream to a Windows Runtime stream by using one of the following `System.IO.WindowsRuntimeStreamExtensions` methods: - - `System.IO.WindowsRuntimeStreamExtensions.AsInputStream` - Converts a managed stream in the .NET for Windows Store apps subset to an input stream in the Windows Runtime. - - `System.IO.WindowsRuntimeStreamExtensions.AsOutputStream` - Converts a managed stream in the .NET for Windows Store apps subset to an output stream in the Windows Runtime. - - [AsRandomAccessStream](../../../docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md) - Converts a managed stream in the .NET for Windows Store apps subset to a random-access stream that can be used for reading or writing in the Windows Runtime. - - When you convert a .NET Framework stream to a Windows Runtime stream, the capabilities of the converted stream will depend on the original stream. For example, if the original stream supports both reading and writing, and you call `System.IO.WindowsRuntimeStreamExtensions.AsInputStream` to convert the stream, the returned type will be an `IRandomAccessStream`, which implements `IInputStream` and `IOutputStream`, and supports reading and writing - - .NET Framework streams do not support cloning, even after conversion. This means that if you convert a .NET Framework stream to a Windows Runtime stream and call [GetInputStreamAt](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.inmemoryrandomaccessstream.getinputstreamat.aspx) or [GetOutputStreamAt](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.irandomaccessstream.getoutputstreamat.aspx), which call [CloneStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.randomaccessstreamoverstream.clonestream.aspx) or call [CloneStream](http://msdn.microsoft.com/library/windows/apps/windows.storage.streams.randomaccessstreamoverstream.clonestream.aspx) directly, an exception will occur. - -#### To convert from a .NET Framework stream to a Windows Runtime random-access stream - -- Use the [AsRandomAccessStream](../../../docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md) method, as shown in the following example. - - > [!IMPORTANT] - > Ensure that the .NET Framework stream you are using supports seeking, or copy it to a stream that does. You can use the property to determine this. - - To run this example, you must create a Windows Store XAML app that targets the .NET Framework 4.5.1 and contains a text block named `TextBlock2` and a button named `Button2`. The button click event must be associated with the `button2_Click` method shown in this example. - - [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#imports)] - [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#imports)] - [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#2)] - [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#2)] - -## See Also - [Quickstart: Reading and writing a file (Windows)](https://msdn.microsoft.com/library/windows/apps/hh464978.aspx) - [.NET for Windows Store apps overview](http://msdn.microsoft.com/library/windows/apps/br230302.aspx) - [.NET for Windows Store apps – supported APIs](https://msdn.microsoft.com/library/windows/apps/br230232.aspx) + +The .NET Framework for Windows Store apps is a subset of the full .NET Framework. Because of security and other requirements for Windows Store apps, you cannot use the full set of .NET Framework APIs to open and read files. For more information, see [.NET for Windows Store apps overview](https://docs.microsoft.com/previous-versions/windows/apps/br230302(v=vs.140)). However, you may want to use .NET Framework APIs for other stream manipulation operations. To manipulate these streams, you may find it necessary to convert between a .NET Framework stream type such as or , and a Windows Runtime stream such as , , or . + +The [System.IO.WindowsRuntimeStreamExtensions](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.aspx) class contains methods that make these conversions easy. However, there are underlying differences between streams in the .NET Framework and the Windows Runtime that will affect the results of using these methods. The details are described in the following sections. + +## Converting from a Windows Runtime stream to a .NET Framework stream + +You can convert from a Windows Runtime stream to a .NET Framework stream by using one of the following [System.IO.WindowsRuntimeStreamExtensions](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.aspx) methods: + +[System.IO.WindowsRuntimeStreamExtensions.AsStream](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asstream.aspx) +Converts a random-access stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. + +[System.IO.WindowsRuntimeStreamExtensions.AsStreamForWrite](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asstreamforwrite.aspx) +Converts an output stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. + +[System.IO.WindowsRuntimeStreamExtensions.AsStreamForRead](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asstreamforread.aspx) +Converts an input stream in the Windows Runtime to a managed stream in the .NET for Windows Store apps subset. + +The Windows Runtime offers stream types that support reading only, writing only or reading and writing, and these capabilities are maintained when you convert a Windows Runtime stream to a .NET Framework stream. Furthermore, if you convert a Windows Runtime stream to a .NET Framework stream and back, you get the original Windows Runtime instance back. It’s best practice to use the conversion method that matches the capabilities of the Windows Runtime stream you would like to convert. However, since is readable and writeable (it implements both and , you can use any of the conversion methods and the capabilities of the original stream are maintained. For example, using [System.IO.WindowsRuntimeStreamExtensions.AsStreamForRead](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asstreamforread.aspx) to convert an will not limit the converted .NET Framework stream to being readable only; it will also be writable. + +### To convert from a Windows Runtime random-access stream to a .NET Framework stream + +- Use the [System.IO.WindowsRuntimeStreamExtensions.AsStream](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asstream.aspx) method. + + The following code example shows how to prompt the user to select a file, open it with Windows Runtime APIs, and then convert it to a .NET Framework stream, which is read and output to a text block. In this scenario, you would typically manipulate the stream with .NET Framework APIs before outputting the results. + + To run this example, you must create a Windows Store XAML app that contains a text block named `TextBlock1` and a button named `Button1`. The button click event must be associated with the `button1_Click` method shown in the example. + + [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#imports)] + [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#imports)] + [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#1)] + [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#1)] + +## Converting from a .NET Framework stream to a Windows Runtime stream + +You can convert from a .NET Framework stream to a Windows Runtime stream by using one of the following [System.IO.WindowsRuntimeStreamExtensions](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.aspx) methods: + +[System.IO.WindowsRuntimeStreamExtensions.AsInputStream](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asinputstream.aspx) + Converts a managed stream in the .NET for Windows Store apps subset to an input stream in the Windows Runtime. + +[System.IO.WindowsRuntimeStreamExtensions.AsOutputStream](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asoutputstream.aspx) + Converts a managed stream in the .NET for Windows Store apps subset to an output stream in the Windows Runtime. + +[AsRandomAccessStream](../../../docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md) + Converts a managed stream in the .NET for Windows Store apps subset to a random-access stream that can be used for reading or writing in the Windows Runtime. + +When you convert a .NET Framework stream to a Windows Runtime stream, the capabilities of the converted stream will depend on the original stream. For example, if the original stream supports both reading and writing, and you call[System.IO.WindowsRuntimeStreamExtensions.AsInputStream](https://msdn.microsoft.com/library/system.io.windowsruntimestreamextensions.asinputstream.aspx) to convert the stream, the returned type will be an `IRandomAccessStream`, which implements `IInputStream` and `IOutputStream`, and supports reading and writing. + +.NET Framework streams do not support cloning, even after conversion. This means that if you convert a .NET Framework stream to a Windows Runtime stream and call or , which call or call directly, an exception will occur. + +### To convert from a .NET Framework stream to a Windows Runtime random-access stream + +- Use the [AsRandomAccessStream](../../../docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md) method, as shown in the following example: + + > [!IMPORTANT] + > Ensure that the .NET Framework stream you are using supports seeking, or copy it to a stream that does. You can use the property to determine this. + + To run this example, you must create a Windows Store XAML app that targets the .NET Framework 4.5.1 and contains a text block named `TextBlock2` and a button named `Button2`. The button click event must be associated with the `button2_Click` method shown in this example. + + [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#imports)] + [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#Imports](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#imports)] + [!code-csharp[System.IO.WindowsRuntimeStreamExtensionsEx#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/cs/mainpage.xaml.cs#2)] + [!code-vb[System.IO.WindowsRuntimeStreamExtensionsEx#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestreamextensionsex/vb/mainpage.xaml.vb#2)] + +## See Also + +[Quickstart: Reading and writing a file (Windows)](https://msdn.microsoft.com/library/windows/apps/hh464978.aspx) +[.NET for Windows Store apps overview](http://msdn.microsoft.com/library/windows/apps/br230302.aspx) +[.NET for Windows Store apps – supported APIs](https://msdn.microsoft.com/library/windows/apps/br230232.aspx) \ No newline at end of file diff --git a/docs/standard/microservices-architecture/container-docker-introduction/docker-defined.md b/docs/standard/microservices-architecture/container-docker-introduction/docker-defined.md index 12132c0ac835e..69c3d650d5080 100644 --- a/docs/standard/microservices-architecture/container-docker-introduction/docker-defined.md +++ b/docs/standard/microservices-architecture/container-docker-introduction/docker-defined.md @@ -17,7 +17,7 @@ Docker image containers run natively on Linux and Windows. Windows images run on You can develop on Windows, Linux, or macOS. The development computer runs a Docker host where Docker images are deployed, including the app and its dependencies. On Linux or macOS, you use a Docker host that is Linux based and can create images only for Linux containers.(On macOS you can edit code or run the Docker CLI, but as of the time of this writing, containers do not run directly on macOS.) On Windows you can create images for either Linux or Windows Containers. -On Windows or macOS, [Docker Community Edition (CE)](https://www.docker.com/community-edition) hosts containers in a development environment and provides additional developer tools. [Docker Enterprise Edition (EE)](https://www.docker.com/enterprise-edition) is used by IT teams who build, ship, and run large business-critical applications. ~Both products install the necessary VM (the Docker host) to host the containers.~ +On Windows or macOS, [Docker Community Edition (CE)](https://www.docker.com/community-edition) hosts containers in a development environment and provides additional developer tools. [Docker Enterprise Edition (EE)](https://www.docker.com/enterprise-edition) is used by IT teams who build, ship, and run large business-critical applications. Both products install the necessary VM (the Docker host) to host the containers. [Windows Containers](https://msdn.microsoft.com/en-us/virtualization/windowscontainers/about/about_overview) work with two types of runtimes: diff --git a/docs/standard/microservices-architecture/microservice-ddd-cqrs-patterns/client-side-validation.md b/docs/standard/microservices-architecture/microservice-ddd-cqrs-patterns/client-side-validation.md index 722939f5c3464..a1f9c54713803 100644 --- a/docs/standard/microservices-architecture/microservice-ddd-cqrs-patterns/client-side-validation.md +++ b/docs/standard/microservices-architecture/microservice-ddd-cqrs-patterns/client-side-validation.md @@ -17,7 +17,7 @@ Even when using client-side validation, you should always validate your commands Therefore, in client-side code you typically validate the ViewModels. You could also validate the client output DTOs or commands before you send them to the services. -The implementation of client-side validation depends on what kind of client application you are building. It will be different if you are validating data in a web MVC web application with most of the code in .NET, an SPA web application with that validation being coded in JavaScript or TypeScript, or a mobile app coded with Xamarin and C\#. +The implementation of client-side validation depends on what kind of client application you are building. It will be different if you are validating data in a web MVC web application with most of the code in .NET, an SPA web application with that validation being coded in JavaScript or TypeScript, or a mobile app coded with Xamarin and C#. ## Additional resources @@ -36,8 +36,8 @@ The implementation of client-side validation depends on what kind of client appl ### Validation in SPA Web apps (Angular 2, TypeScript, JavaScript) -- **Ado Kukic. Angular 2 Form Validation** ** - **[*https://scotch.io/tutorials/angular-2-form-validation*](https://scotch.io/tutorials/angular-2-form-validation) +- **Ado Kukic. Angular 2 Form Validation** + [*https://scotch.io/tutorials/angular-2-form-validation*](https://scotch.io/tutorials/angular-2-form-validation) - **Form Validation** [*https://angular.io/docs/ts/latest/cookbook/form-validation.html*](https://angular.io/docs/ts/latest/cookbook/form-validation.html) @@ -47,17 +47,16 @@ The implementation of client-side validation depends on what kind of client appl In summary, these are the most important concepts in regards to validation: -- Entities and aggregates should enforce their own consistency and be "always valid”. Aggregate roots are responsible for multi-entity consistency within the same aggregate. +- Entities and aggregates should enforce their own consistency and be "always valid”. Aggregate roots are responsible for multi-entity consistency within the same aggregate. -- If you think that an entity needs to enter an invalid state, consider using a different object model—for example, using a temporary DTO until you create the final domain entity. +- If you think that an entity needs to enter an invalid state, consider using a different object model—for example, using a temporary DTO until you create the final domain entity. -- If you need to create several related objects, such as an aggregate, and they are only valid once all of them have been created, consider using the Factory pattern. +- If you need to create several related objects, such as an aggregate, and they are only valid once all of them have been created, consider using the Factory pattern. -- Validation frameworks are best used in specific layers, such as the presentation layer or the application/service layer, but usually not in the domain model layer, because you would need to take a strong dependency on an infrastructure framework. - -- In most of the cases, having redundant validation in the client side is good, because the application can be proactive. +- Validation frameworks are best used in specific layers, such as the presentation layer or the application/service layer, but usually not in the domain model layer, because you would need to take a strong dependency on an infrastructure framework. +- In most of the cases, having redundant validation in the client side is good, because the application can be proactive. >[!div class="step-by-step"] [Previous](domain-model-layer-validations.md) -[Next](domain-events-design-implementation.md) +[Next](domain-events-design-implementation.md) \ No newline at end of file diff --git a/docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md b/docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md index 58375a2a00938..239913c99cd58 100644 --- a/docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md +++ b/docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md @@ -9,27 +9,29 @@ helpviewer_keywords: - "serialization, attributes" ms.assetid: 93ee258c-9c0f-4a08-897c-c10db7a00f91 --- -# Attributes That Control Encoded SOAP Serialization -The World Wide Web Consortium (www.w3.org) document named "Simple Object Access Protocol (SOAP) 1.1" contains an optional section (section 5) that describes how SOAP parameters can be encoded. To conform to section 5 of the specification, you must use a special set of attributes found in the namespace. Apply those attributes as appropriate to classes and members of classes, and then use the to serialize instances of the class or classes. - - The following table shows the attributes, where they can be applied, and what they do. For more information about using these attributes to control XML serialization, see [How to: Serialize an Object as a SOAP-Encoded XML Stream](../../../docs/standard/serialization/how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) and [How to: Override Encoded SOAP XML Serialization](../../../docs/standard/serialization/how-to-override-encoded-soap-xml-serialization.md). - - For more information about attributes, see [Attributes](../../../docs/standard/attributes/index.md). - -|Attribute|Applies to|Specifies| -|---------------|----------------|---------------| -||Public field, property, parameter, or return value.|The class member will be serialized as an XML attribute.| -||Public field, property, parameter, or return value.|The class will be serialized as an XML element.| -||Public field that is an enumeration identifier.|The element name of an enumeration member.| -||Public properties and fields.|The property or field should be ignored when the containing class is serialized.| -||Public-derived class declarations and public methods for Web Services Description Language (WSDL) documents.|The type should be included when generating schemas (to be recognized when serialized).| -||Public class declarations.|The class should be serialized as an XML type.| - -## See Also - [XML and SOAP Serialization](../../../docs/standard/serialization/xml-and-soap-serialization.md) - [How to: Serialize an Object as a SOAP-Encoded XML Stream](../../../docs/standard/serialization/how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) - [How to: Override Encoded SOAP XML Serialization](../../../docs/standard/serialization/how-to-override-encoded-soap-xml-serialization.md) - [Attributes](../../../docs/standard/attributes/index.md) - - [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) - [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md) +# Attributes That Control Encoded SOAP Serialization + +The World Wide Web Consortium (W3C) document named [Simple Object Access Protocol (SOAP) 1.1](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/) contains an optional section (section 5) that describes how SOAP parameters can be encoded. To conform to section 5 of the specification, you must use a special set of attributes found in the namespace. Apply those attributes as appropriate to classes and members of classes, and then use the to serialize instances of the class or classes. + +The following table shows the attributes, where they can be applied, and what they do. For more information about using these attributes to control XML serialization, see [How to: Serialize an Object as a SOAP-Encoded XML Stream](how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) and [How to: Override Encoded SOAP XML Serialization](how-to-override-encoded-soap-xml-serialization.md). + +For more information about attributes, see [Attributes](../../../docs/standard/attributes/index.md). + +|Attribute|Applies to|Specifies| +|---------------|----------------|---------------| +||Public field, property, parameter, or return value.|The class member will be serialized as an XML attribute.| +||Public field, property, parameter, or return value.|The class will be serialized as an XML element.| +||Public field that is an enumeration identifier.|The element name of an enumeration member.| +||Public properties and fields.|The property or field should be ignored when the containing class is serialized.| +||Public-derived class declarations and public methods for Web Services Description Language (WSDL) documents.|The type should be included when generating schemas (to be recognized when serialized).| +||Public class declarations.|The class should be serialized as an XML type.| + +## See Also + +[XML and SOAP Serialization](xml-and-soap-serialization.md) +[How to: Serialize an Object as a SOAP-Encoded XML Stream](how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) +[How to: Override Encoded SOAP XML Serialization](how-to-override-encoded-soap-xml-serialization.md) +[Attributes](../../../docs/standard/attributes/index.md) + +[How to: Serialize an Object](how-to-serialize-an-object.md) +[How to: Deserialize an Object](how-to-deserialize-an-object.md) \ No newline at end of file diff --git a/docs/standard/serialization/controlling-xml-serialization-using-attributes.md b/docs/standard/serialization/controlling-xml-serialization-using-attributes.md index e80701eaccd71..b6bacb32b5a57 100644 --- a/docs/standard/serialization/controlling-xml-serialization-using-attributes.md +++ b/docs/standard/serialization/controlling-xml-serialization-using-attributes.md @@ -17,296 +17,304 @@ helpviewer_keywords: ms.assetid: 47d4c39d-30e1-4c7b-8a2e-301325390647 --- # Controlling XML Serialization Using Attributes -Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. For more details about creating an alternate XML stream, see [How to: Specify an Alternate Element Name for an XML Stream](../../../docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md). - + +Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. For more details about creating an alternate XML stream, see [How to: Specify an Alternate Element Name for an XML Stream](how-to-specify-an-alternate-element-name-for-an-xml-stream.md). + > [!NOTE] -> If the XML generated must conform to section 5 of the World Wide Web Consortium (www.w3.org) document titled "Simple Object Access Protocol (SOAP) 1.1," use the attributes listed in [Attributes That Control Encoded SOAP Serialization](../../../docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md). - - By default, an XML element name is determined by the class or member name. In a simple class named `Book`, a field named `ISBN` will produce an XML element tag \, as shown in the following example. - -```vb -Public Class Book - Public ISBN As String -End Class -' When an instance of the Book class is serialized, it might -' produce this XML: -' 1234567890. -``` - -```csharp -public class Book -{ - public string ISBN; -} -// When an instance of the Book class is serialized, it might -// produce this XML: -// 1234567890. -``` - - This default behavior can be changed if you want to give the element a new name. The following code shows how an attribute enables this by setting the property of a . - -```vb -Public Class TaxRates - < XmlElement(ElementName = "TaxRate")> _ - Public ReturnTaxRate As Decimal -End Class -``` - -```csharp -public class TaxRates { - [XmlElement(ElementName = "TaxRate")] - public decimal ReturnTaxRate; -} -``` - - For more information about attributes, see [Attributes](../../../docs/standard/attributes/index.md). For a list of attributes that control XML serialization, see [Attributes That Control XML Serialization](../../../docs/standard/serialization/attributes-that-control-xml-serialization.md). - -## Controlling Array Serialization - The and the attributes are designed to control the serialization of arrays. Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). You can also specify the types that can be included in an array. - - The will determine the properties of the enclosing XML element that results when an array is serialized. For example, by default, serializing the array below will result in an XML element named `Employees`. The `Employees` element will contain a series of elements named after the array type `Employee`. - -```vb -Public Class Group - Public Employees() As Employee -End Class -Public Class Employee - Public Name As String -End Class -``` - -```csharp -public class Group { - public Employee[] Employees; -} -public class Employee { - public string Name; -} -``` - - A serialized instance might resemble the following. - -```xml - - - - Haley - - - -``` - - By applying a , you can change the name of the XML element, as follows. - -```vb -Public Class Group - _ - Public Employees() As Employee -End Class -``` - -```csharp -public class Group { - [XmlArray("TeamMembers")] - public Employee[] Employees; -} -``` - - The resulting XML might resemble the following. - -```xml - - - - Haley - - - -``` - - The , on the other hand, controls how the items contained in the array are serialized. Note that the attribute is applied to the field returning the array. - -```vb -Public Class Group - _ - Public Employee() As Employees -End Class -``` - -```csharp -public class Group { - [XmlArrayItem("MemberName")] - public Employee[] Employees; -} -``` - - The resulting XML might resemble the following. - -```xml - - - Haley - - -``` - -## Serializing Derived Classes - Another use of the is to allow the serialization of derived classes. For example, another class named `Manager` that derives from `Employee` can be added to the previous example. If you do not apply the , the code will fail at run time because the derived class type will not be recognized. To remedy this, apply the attribute twice, each time setting the property for each acceptable type (base and derived). - -```vb -Public Class Group - _ - Public Employees() As Employee -End Class -Public Class Employee - Public Name As String -End Class -Public Class Manager -Inherits Employee - Public Level As Integer -End Class -``` - -```csharp -public class Group { - [XmlArrayItem(Type = typeof(Employee)), - XmlArrayItem(Type = typeof(Manager))] - public Employee[] Employees; -} -public class Employee { - public string Name; -} -public class Manager:Employee { - public int Level; -} -``` - - A serialized instance might resemble the following. - -```xml - - - - Haley - - - Ann - 3 - - - -``` - -## Serializing an Array as a Sequence of Elements - You can also serialize an array as a flat sequence of XML elements by applying a to the field returning the array as follows. - -```vb -Public Class Group - _ - Public Employees() As Employee -End Class -``` - -```csharp -public class Group { - [XmlElement] - public Employee[] Employees; -} -``` - - A serialized instance might resemble the following. - -```xml - - - Haley - - - Noriko - - - Marco - - -``` - - Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (For more details on using the tool, see [The XML Schema Definition Tool and XML Serialization](../../../docs/standard/serialization/the-xml-schema-definition-tool-and-xml-serialization.md).) When no attribute is applied to the field, the schema describes the element in the following manner. - -```xml - -``` - - When the is applied to the field, the resulting schema describes the element as follows. - -```xml - -``` - -## Serializing an ArrayList - The class can contain a collection of diverse objects. You can therefore use a much as you use an array. Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single . However, as with arrays, you must inform the of the types of objects the contains. To accomplish this, assign multiple instances of the to the field, as shown in the following example. - -```vb -Public Class Group - _ - Public Info As ArrayList -End Class -``` - -```csharp -public class Group { - [XmlElement(Type = typeof(Employee)), - XmlElement(Type = typeof(Manager))] - public ArrayList Info; -} -``` - -## Controlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute - There are two attributes that can be applied to a class (and only a class): and . These attributes are very similar. The can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. The , on the other hand, can be applied to any class, including the root class. - - For example, in the previous examples, the `Group` class is the root class, and all its public fields and properties become the XML elements found in the XML document. Therefore, there can be only one root class. By applying the , you can control the XML stream generated by the . For example, you can change the element name and namespace. - - The allows you to control the schema of the generated XML. This capability is useful when you need to publish the schema through an XML Web service. The following example applies both the and the to the same class. - -```vb - _ -Public Class Group - Public Employees() As Employee -End Class -``` - -```csharp -[XmlRoot("NewGroupName")] -[XmlType("NewTypeName")] -public class Group { - public Employee[] Employees; -} -``` - - If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing `Group`. - -```xml - -``` - - In contrast, if you were to serialize an instance of the class, only `NewGroupName` would be found in the XML document. - -```xml - - . . . - -``` - -## Preventing Serialization with the XmlIgnoreAttribute - There might be situations when a public property or field does not need to be serialized. For example, a field or property could be used to contain metadata. In such cases, apply the to the field or property and the will skip over it. - -## See Also - [Attributes That Control XML Serialization](../../../docs/standard/serialization/attributes-that-control-xml-serialization.md) - [Attributes That Control Encoded SOAP Serialization](../../../docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md) - [Introducing XML Serialization](../../../docs/standard/serialization/introducing-xml-serialization.md) - [Examples of XML Serialization](../../../docs/standard/serialization/examples-of-xml-serialization.md) - [How to: Specify an Alternate Element Name for an XML Stream](../../../docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md) - [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) - [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md) +> If the XML generated must conform to section 5 of the World Wide Web Consortium (W3C) document titled [Simple Object Access Protocol (SOAP) 1.1](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/), use the attributes listed in [Attributes That Control Encoded SOAP Serialization](attributes-that-control-encoded-soap-serialization.md). + +By default, an XML element name is determined by the class or member name. In a simple class named `Book`, a field named `ISBN` will produce an XML element tag \, as shown in the following example. + +```vb +Public Class Book + Public ISBN As String +End Class +' When an instance of the Book class is serialized, it might +' produce this XML: +' 1234567890. +``` + +```csharp +public class Book +{ + public string ISBN; +} +// When an instance of the Book class is serialized, it might +// produce this XML: +// 1234567890. +``` + +This default behavior can be changed if you want to give the element a new name. The following code shows how an attribute enables this by setting the property of a . + +```vb +Public Class TaxRates + < XmlElement(ElementName = "TaxRate")> _ + Public ReturnTaxRate As Decimal +End Class +``` + +```csharp +public class TaxRates { + [XmlElement(ElementName = "TaxRate")] + public decimal ReturnTaxRate; +} +``` + +For more information about attributes, see [Attributes](../../../docs/standard/attributes/index.md). For a list of attributes that control XML serialization, see [Attributes That Control XML Serialization](attributes-that-control-xml-serialization.md). + +## Controlling Array Serialization + +The and the attributes are designed to control the serialization of arrays. Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). You can also specify the types that can be included in an array. + +The will determine the properties of the enclosing XML element that results when an array is serialized. For example, by default, serializing the array below will result in an XML element named `Employees`. The `Employees` element will contain a series of elements named after the array type `Employee`. + +```vb +Public Class Group + Public Employees() As Employee +End Class +Public Class Employee + Public Name As String +End Class +``` + +```csharp +public class Group { + public Employee[] Employees; +} +public class Employee { + public string Name; +} +``` + +A serialized instance might resemble the following. + +```xml + + + + Haley + + + +``` + +By applying a , you can change the name of the XML element, as follows. + +```vb +Public Class Group + _ + Public Employees() As Employee +End Class +``` + +```csharp +public class Group { + [XmlArray("TeamMembers")] + public Employee[] Employees; +} +``` + +The resulting XML might resemble the following. + +```xml + + + + Haley + + + +``` + +The , on the other hand, controls how the items contained in the array are serialized. Note that the attribute is applied to the field returning the array. + +```vb +Public Class Group + _ + Public Employee() As Employees +End Class +``` + +```csharp +public class Group { + [XmlArrayItem("MemberName")] + public Employee[] Employees; +} +``` + +The resulting XML might resemble the following. + +```xml + + + Haley + + +``` + +## Serializing Derived Classes + +Another use of the is to allow the serialization of derived classes. For example, another class named `Manager` that derives from `Employee` can be added to the previous example. If you do not apply the , the code will fail at run time because the derived class type will not be recognized. To remedy this, apply the attribute twice, each time setting the property for each acceptable type (base and derived). + +```vb +Public Class Group + _ + Public Employees() As Employee +End Class +Public Class Employee + Public Name As String +End Class +Public Class Manager +Inherits Employee + Public Level As Integer +End Class +``` + +```csharp +public class Group { + [XmlArrayItem(Type = typeof(Employee)), + XmlArrayItem(Type = typeof(Manager))] + public Employee[] Employees; +} +public class Employee { + public string Name; +} +public class Manager:Employee { + public int Level; +} +``` + +A serialized instance might resemble the following. + +```xml + + + + Haley + + + Ann + 3 + + + +``` + +## Serializing an Array as a Sequence of Elements + +You can also serialize an array as a flat sequence of XML elements by applying a to the field returning the array as follows. + +```vb +Public Class Group + _ + Public Employees() As Employee +End Class +``` + +```csharp +public class Group { + [XmlElement] + public Employee[] Employees; +} +``` + +A serialized instance might resemble the following. + +```xml + + + Haley + + + Noriko + + + Marco + + +``` + +Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (For more details on using the tool, see [The XML Schema Definition Tool and XML Serialization](the-xml-schema-definition-tool-and-xml-serialization.md).) When no attribute is applied to the field, the schema describes the element in the following manner. + +```xml + +``` + +When the is applied to the field, the resulting schema describes the element as follows. + +```xml + +``` + +## Serializing an ArrayList + +The class can contain a collection of diverse objects. You can therefore use a much as you use an array. Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single . However, as with arrays, you must inform the of the types of objects the contains. To accomplish this, assign multiple instances of the to the field, as shown in the following example. + +```vb +Public Class Group + _ + Public Info As ArrayList +End Class +``` + +```csharp +public class Group { + [XmlElement(Type = typeof(Employee)), + XmlElement(Type = typeof(Manager))] + public ArrayList Info; +} +``` + +## Controlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute + +There are two attributes that can be applied to a class (and only a class): and . These attributes are very similar. The can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. The , on the other hand, can be applied to any class, including the root class. + +For example, in the previous examples, the `Group` class is the root class, and all its public fields and properties become the XML elements found in the XML document. Therefore, there can be only one root class. By applying the , you can control the XML stream generated by the . For example, you can change the element name and namespace. + +The allows you to control the schema of the generated XML. This capability is useful when you need to publish the schema through an XML Web service. The following example applies both the and the to the same class. + +```vb + _ +Public Class Group + Public Employees() As Employee +End Class +``` + +```csharp +[XmlRoot("NewGroupName")] +[XmlType("NewTypeName")] +public class Group { + public Employee[] Employees; +} +``` + +If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing `Group`. + +```xml + +``` + +In contrast, if you were to serialize an instance of the class, only `NewGroupName` would be found in the XML document. + +```xml + + . . . + +``` + +## Preventing Serialization with the XmlIgnoreAttribute + +There might be situations when a public property or field does not need to be serialized. For example, a field or property could be used to contain metadata. In such cases, apply the to the field or property and the will skip over it. + +## See Also + +[Attributes That Control XML Serialization](attributes-that-control-xml-serialization.md) +[Attributes That Control Encoded SOAP Serialization](attributes-that-control-encoded-soap-serialization.md) +[Introducing XML Serialization](introducing-xml-serialization.md) +[Examples of XML Serialization](examples-of-xml-serialization.md) +[How to: Specify an Alternate Element Name for an XML Stream](how-to-specify-an-alternate-element-name-for-an-xml-stream.md) +[How to: Serialize an Object](how-to-serialize-an-object.md) +[How to: Deserialize an Object](how-to-deserialize-an-object.md) \ No newline at end of file diff --git a/docs/standard/serialization/how-to-qualify-xml-element-and-xml-attribute-names.md b/docs/standard/serialization/how-to-qualify-xml-element-and-xml-attribute-names.md index 2e8c82d698c1a..f009e3e1ea323 100644 --- a/docs/standard/serialization/how-to-qualify-xml-element-and-xml-attribute-names.md +++ b/docs/standard/serialization/how-to-qualify-xml-element-and-xml-attribute-names.md @@ -11,164 +11,165 @@ helpviewer_keywords: ms.assetid: 44719f90-7e15-42e8-a9e2-282287e2b5bf --- # How to: Qualify XML Element and XML Attribute Names -[Code Example](#cpconworkingwithxmlnamespacesanchor1) - - XML namespaces contained by instances of the class must conform to the World Wide Web Consortium (www.w3.org) specification called "Namespaces in XML." - - XML namespaces provide a method for qualifying the names of XML elements and XML attributes in XML documents. A qualified name consists of a prefix and a local name, separated by a colon. The prefix functions only as a placeholder; it is mapped to a URI that specifies a namespace. The combination of the universally managed URI namespace and the local name produces a name that is guaranteed to be universally unique. - - By creating an instance of `XmlSerializerNamespaces` and adding the namespace pairs to the object, you can specify the prefixes used in an XML document. - -### To create qualified names in an XML document - -1. Create an instance of the `XmlSerializerNamespaces` class. - -2. Add all prefixes and namespace pairs to the `XmlSerializerNamespaces`. - -3. Apply the appropriate `System.Xml.Serialization` attribute to each member or class that the is to serialize into an XML document. - - The available attributes are: , , , , , , and . - -4. Set the `Namespace` property of each attribute to one of the namespace values from the `XmlSerializerNamespaces`. - -5. Pass the `XmlSerializerNamespaces` to the `Serialize` method of the `XmlSerializer`. - -## Example - The following example creates an `XmlSerializerNamespaces`, and adds two prefix and namespace pairs to the object. The code creates an `XmlSerializer` that is used to serialize an instance of the `Books` class. The code calls the `Serialize` method with the `XmlSerializerNamespaces`, allowing the XML to contain prefixed namespaces. - -```vb -Option Explicit -public class Price -{ - [XmlAttribute(Namespace = "http://www.cpandl.com")] - public string currency; - [XmlElement(Namespace = "http://www.cohowinery.com")] - public decimal price; -} - -Option Strict - -Imports System -Imports System.IO -Imports System.Xml -Imports System.Xml.Serialization - -Public Class Run - - Public Shared Sub Main() - Dim test As New Run() - test.SerializeObject("XmlNamespaces.xml") - End Sub 'Main - - Public Sub SerializeObject(filename As String) - Dim mySerializer As New XmlSerializer(GetType(Books)) - ' Writing a file requires a TextWriter. - Dim myWriter As New StreamWriter(filename) - - ' Creates an XmlSerializerNamespaces and adds two - ' prefix-namespace pairs. - Dim myNamespaces As New XmlSerializerNamespaces() - myNamespaces.Add("books", "http://www.cpandl.com") - myNamespaces.Add("money", "http://www.cohowinery.com") - - ' Creates a Book. - Dim myBook As New Book() - myBook.TITLE = "A Book Title" - Dim myPrice As New Price() - myPrice.price = CDec(9.95) - myPrice.currency = "US Dollar" - myBook.PRICE = myPrice - Dim myBooks As New Books() - myBooks.Book = myBook - mySerializer.Serialize(myWriter, myBooks, myNamespaces) - myWriter.Close() - End Sub -End Class - -Public Class Books - _ - Public Book As Book -End Class 'Books - - _ -Public Class Book - - _ - Public TITLE As String - _ - Public PRICE As Price -End Class - -Public Class Price - _ - Public currency As String - Public _ - price As Decimal -End Class -``` - -```csharp -using System; -using System.IO; -using System.Xml; -using System.Xml.Serialization; - -public class Run -{ - public static void Main() - { - Run test = new Run(); - test.SerializeObject("XmlNamespaces.xml"); - } - public void SerializeObject(string filename) - { - XmlSerializer mySerializer = new XmlSerializer(typeof(Books)); - // Writing a file requires a TextWriter. - TextWriter myWriter = new StreamWriter(filename); - - // Creates an XmlSerializerNamespaces and adds two - // prefix-namespace pairs. - XmlSerializerNamespaces myNamespaces = - new XmlSerializerNamespaces(); - myNamespaces.Add("books", "http://www.cpandl.com"); - myNamespaces.Add("money", "http://www.cohowinery.com"); - - // Creates a Book. - Book myBook = new Book(); - myBook.TITLE = "A Book Title"; - Price myPrice = new Price(); - myPrice.price = (decimal) 9.95; - myPrice.currency = "US Dollar"; - myBook.PRICE = myPrice; - Books myBooks = new Books(); - myBooks.Book = myBook; - mySerializer.Serialize(myWriter,myBooks,myNamespaces); - myWriter.Close(); - } -} - -public class Books -{ - [XmlElement(Namespace = "http://www.cohowinery.com")] - public Book Book; -} - -[XmlType(Namespace ="http://www.cpandl.com")] -public class Book -{ - [XmlElement(Namespace = "http://www.cpandl.com")] - public string TITLE; - [XmlElement(Namespace ="http://www.cohowinery.com")] - public Price PRICE; -} -``` - -## See Also - - [The XML Schema Definition Tool and XML Serialization](../../../docs/standard/serialization/the-xml-schema-definition-tool-and-xml-serialization.md) - [Introducing XML Serialization](../../../docs/standard/serialization/introducing-xml-serialization.md) - [XmlSerializer Class](xref:System.Xml.Serialization.XmlSerializer) - [Attributes That Control XML Serialization](../../../docs/standard/serialization/attributes-that-control-xml-serialization.md) - [How to: Specify an Alternate Element Name for an XML Stream](../../../docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md) - [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) - [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md) + +XML namespaces contained by instances of the class must conform to the World Wide Web Consortium (W3C) specification called [Namespaces in XML](https://www.w3.org/TR/REC-xml-names/). + +XML namespaces provide a method for qualifying the names of XML elements and XML attributes in XML documents. A qualified name consists of a prefix and a local name, separated by a colon. The prefix functions only as a placeholder; it is mapped to a URI that specifies a namespace. The combination of the universally managed URI namespace and the local name produces a name that is guaranteed to be universally unique. + +By creating an instance of `XmlSerializerNamespaces` and adding the namespace pairs to the object, you can specify the prefixes used in an XML document. + +## To create qualified names in an XML document + +1. Create an instance of the `XmlSerializerNamespaces` class. + +2. Add all prefixes and namespace pairs to the `XmlSerializerNamespaces`. + +3. Apply the appropriate `System.Xml.Serialization` attribute to each member or class that the is to serialize into an XML document. + + The available attributes are: , , , , , , and . + +4. Set the `Namespace` property of each attribute to one of the namespace values from the `XmlSerializerNamespaces`. + +5. Pass the `XmlSerializerNamespaces` to the `Serialize` method of the `XmlSerializer`. + +## Example + +The following example creates an `XmlSerializerNamespaces`, and adds two prefix and namespace pairs to the object. The code creates an `XmlSerializer` that is used to serialize an instance of the `Books` class. The code calls the `Serialize` method with the `XmlSerializerNamespaces`, allowing the XML to contain prefixed namespaces. + +```vb +Option Explicit +public class Price +{ + [XmlAttribute(Namespace = "http://www.cpandl.com")] + public string currency; + [XmlElement(Namespace = "http://www.cohowinery.com")] + public decimal price; +} + +Option Strict + +Imports System +Imports System.IO +Imports System.Xml +Imports System.Xml.Serialization + +Public Class Run + + Public Shared Sub Main() + Dim test As New Run() + test.SerializeObject("XmlNamespaces.xml") + End Sub 'Main + + Public Sub SerializeObject(filename As String) + Dim mySerializer As New XmlSerializer(GetType(Books)) + ' Writing a file requires a TextWriter. + Dim myWriter As New StreamWriter(filename) + + ' Creates an XmlSerializerNamespaces and adds two + ' prefix-namespace pairs. + Dim myNamespaces As New XmlSerializerNamespaces() + myNamespaces.Add("books", "http://www.cpandl.com") + myNamespaces.Add("money", "http://www.cohowinery.com") + + ' Creates a Book. + Dim myBook As New Book() + myBook.TITLE = "A Book Title" + Dim myPrice As New Price() + myPrice.price = CDec(9.95) + myPrice.currency = "US Dollar" + myBook.PRICE = myPrice + Dim myBooks As New Books() + myBooks.Book = myBook + mySerializer.Serialize(myWriter, myBooks, myNamespaces) + myWriter.Close() + End Sub +End Class + +Public Class Books + _ + Public Book As Book +End Class 'Books + + _ +Public Class Book + + _ + Public TITLE As String + _ + Public PRICE As Price +End Class + +Public Class Price + _ + Public currency As String + Public _ + price As Decimal +End Class +``` + +```csharp +using System; +using System.IO; +using System.Xml; +using System.Xml.Serialization; + +public class Run +{ + public static void Main() + { + Run test = new Run(); + test.SerializeObject("XmlNamespaces.xml"); + } + public void SerializeObject(string filename) + { + XmlSerializer mySerializer = new XmlSerializer(typeof(Books)); + // Writing a file requires a TextWriter. + TextWriter myWriter = new StreamWriter(filename); + + // Creates an XmlSerializerNamespaces and adds two + // prefix-namespace pairs. + XmlSerializerNamespaces myNamespaces = + new XmlSerializerNamespaces(); + myNamespaces.Add("books", "http://www.cpandl.com"); + myNamespaces.Add("money", "http://www.cohowinery.com"); + + // Creates a Book. + Book myBook = new Book(); + myBook.TITLE = "A Book Title"; + Price myPrice = new Price(); + myPrice.price = (decimal) 9.95; + myPrice.currency = "US Dollar"; + myBook.PRICE = myPrice; + Books myBooks = new Books(); + myBooks.Book = myBook; + mySerializer.Serialize(myWriter,myBooks,myNamespaces); + myWriter.Close(); + } +} + +public class Books +{ + [XmlElement(Namespace = "http://www.cohowinery.com")] + public Book Book; +} + +[XmlType(Namespace ="http://www.cpandl.com")] +public class Book +{ + [XmlElement(Namespace = "http://www.cpandl.com")] + public string TITLE; + [XmlElement(Namespace ="http://www.cohowinery.com")] + public Price PRICE; +} +``` + +## See Also + + +[The XML Schema Definition Tool and XML Serialization](the-xml-schema-definition-tool-and-xml-serialization.md) +[Introducing XML Serialization](introducing-xml-serialization.md) +[XmlSerializer Class](xref:System.Xml.Serialization.XmlSerializer) +[Attributes That Control XML Serialization](attributes-that-control-xml-serialization.md) +[How to: Specify an Alternate Element Name for an XML Stream](how-to-specify-an-alternate-element-name-for-an-xml-stream.md) +[How to: Serialize an Object](how-to-serialize-an-object.md) +[How to: Deserialize an Object](how-to-deserialize-an-object.md) \ No newline at end of file diff --git a/docs/standard/serialization/introducing-xml-serialization.md b/docs/standard/serialization/introducing-xml-serialization.md index 73f124c10c386..288ea1ee15cf5 100644 --- a/docs/standard/serialization/introducing-xml-serialization.md +++ b/docs/standard/serialization/introducing-xml-serialization.md @@ -14,162 +14,170 @@ helpviewer_keywords: ms.assetid: 8c63200d-db63-4a03-a93d-21641623df62 --- # Introducing XML Serialization -Serialization is the process of converting an object into a form that can be readily transported. For example, you can serialize an object and transport it over the Internet using HTTP between a client and a server. On the other end, deserialization reconstructs the object from the stream. - - XML serialization serializes only the public fields and property values of an object into an XML stream. XML serialization does not include type information. For example, if you have a **Book** object that exists in the **Library** namespace, there is no guarantee that it is deserialized into an object of the same type. - + +Serialization is the process of converting an object into a form that can be readily transported. For example, you can serialize an object and transport it over the Internet using HTTP between a client and a server. On the other end, deserialization reconstructs the object from the stream. + + XML serialization serializes only the public fields and property values of an object into an XML stream. XML serialization does not include type information. For example, if you have a **Book** object that exists in the **Library** namespace, there is no guarantee that it is deserialized into an object of the same type. + > [!NOTE] -> XML serialization does not convert methods, indexers, private fields, or read-only properties (except read-only collections). To serialize all an object's fields and properties, both public and private, use the instead of XML serialization. - - The central class in XML serialization is the class, and the most important methods in this class are the **Serialize** and **Deserialize** methods. The creates C# files and compiles them into .dll files to perform this serialization. In .NET Framework 2.0, the [XML Serializer Generator Tool (Sgen.exe)](../../../docs/standard/serialization/xml-serializer-generator-tool-sgen-exe.md) is designed to generate these serialization assemblies in advance to be deployed with your application and improve startup performance. The XML stream generated by the **XmlSerializer** is compliant with the World Wide Web Consortium (www.w3.org) XML Schema definition language (XSD) 1.0 recommendation. Furthermore, the data types generated are compliant with the document titled "XML Schema Part 2: Datatypes." - - The data in your objects is described using programming language constructs like classes, fields, properties, primitive types, arrays, and even embedded XML in the form of **XmlElement** or **XmlAttribute** objects. You have the option of creating your own classes, annotated with attributes, or using the XML Schema Definition tool to generate the classes based on an existing XML Schema. - - If you have an XML Schema, you can run the XML Schema Definition tool to produce a set of classes that are strongly typed to the schema and annotated with attributes. When an instance of such a class is serialized, the generated XML adheres to the XML Schema. Provided with such a class, you can program against an easily manipulated object model while being assured that the generated XML conforms to the XML schema. This is an alternative to using other classes in the .NET Framework, such as the **XmlReader** and **XmlWriter** classes, to parse and write an XML stream. For more information, see [XML Documents and Data](../../../docs/standard/data/xml/index.md). These classes allow you to parse any XML stream. In contrast, use the **XmlSerializer** when the XML stream is expected to conform to a known XML Schema. - - Attributes control the XML stream generated by the **XmlSerializer** class, allowing you to set the XML namespace, element name, attribute name, and so on, of the XML stream. For more information about these attributes and how they control XML serialization, see [Controlling XML Serialization Using Attributes](../../../docs/standard/serialization/controlling-xml-serialization-using-attributes.md). For a table of those attributes that are used to control the generated XML, see [Attributes That Control XML Serialization](../../../docs/standard/serialization/attributes-that-control-xml-serialization.md). - - The **XmlSerializer** class can further serialize an object and generate an encoded SOAP XML stream. The generated XML adheres to section 5 of the World Wide Web Consortium document titled "Simple Object Access Protocol (SOAP) 1.1." For more information about this process, see [How to: Serialize an Object as a SOAP-Encoded XML Stream](../../../docs/standard/serialization/how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md). For a table of the attributes that control the generated XML, see [Attributes That Control Encoded SOAP Serialization](../../../docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md). - - The **XmlSerializer** class generates the SOAP messages created by, and passed to, XML Web services. To control the SOAP messages, you can apply attributes to the classes, return values, parameters, and fields found in an XML Web service file (.asmx). You can use both the attributes listed in "Attributes That Control XML Serialization" and "Attributes That Control Encoded SOAP Serialization" because an XML Web service can use either the literal or encoded SOAP style. For more information about using attributes to control the XML generated by an XML Web service, see [XML Serialization with XML Web Services](../../../docs/standard/serialization/xml-serialization-with-xml-web-services.md). For more information about SOAP and XML Web services, see [Customizing SOAP Messages](https://msdn.microsoft.com/en-us/subscriptions/index/dkwy2d72\(v=vs.71\).aspx). - -## Security Considerations for XmlSerializer Applications - When creating an application that uses the **XmlSerializer**, you should be aware of the following items and their implications: - -- The **XmlSerializer** creates C# (.cs) files and compiles them into .dll files in the directory named by the TEMP environment variable; serialization occurs with those DLLs. - - > [!NOTE] - > These serialization assemblies can be generated in advance and signed by using the SGen.exe tool. This does not work a server of Web services. In other words, it is only for client use and for manual serialization. - - The code and the DLLs are vulnerable to a malicious process at the time of creation and compilation. When using a computer running Microsoft Windows NT 4.0 or later, it might be possible for two or more users to share the TEMP directory. Sharing a TEMP directory is dangerous if the two accounts have different security privileges and the higher-privilege account runs an application using the **XmlSerializer**. In this case, one user can breach the computer's security by replacing either the .cs or .dll file that is compiled. To eliminate this concern, always be sure that each account on the computer has its own profile. By default, the TEMP environment variable points to a different directory for each account. - -- If a malicious user sends a continuous stream of XML data to a Web server (a denial of service attack), then the **XmlSerializer** continues to process the data until the computer runs low on resources. - - This kind of attack is eliminated if you are using a computer running Internet Information Services (IIS), and your application is running within IIS. IIS features a gate that does not process streams longer than a set amount (the default is 4 KB). If you create an application that does not use IIS and deserializes with the **XmlSerializer**, you should implement a similar gate that prevents a denial of service attack. - -- The **XmlSerializer** serializes data and runs any code using any type given to it. - - There are two ways in which a malicious object presents a threat. It could run malicious code or it could inject malicious code into the C# file created by the **XmlSerializer**. In the first case, if a malicious object tries to run a destructive procedure, code access security helps prevent any damage from being done. In the second case, there is a theoretical possibility that a malicious object may somehow inject code into the C# file created by the **XmlSerializer**. Although this issue has been examined thoroughly, and such an attack is considered unlikely, you should take the precaution of never serializing data with an unknown and untrusted type. - -- Serialized sensitive data might be vulnerable. - - After the **XmlSerializer**has serialized data, it can be stored as an XML file or other data store. If your data store is available to other processes, or is visible on an intranet or the Internet, the data can be stolen and used maliciously. For example, if you create an application that serializes orders that include credit card numbers, the data is highly sensitive. To help prevent this, always protect the store for your data and take steps to keep it private. - -## Serialization of a Simple Class - The following code example shows a basic class with a public field. - -```vb -Public Class OrderForm - Public OrderDate As DateTime -End Class -``` - -```csharp -public class OrderForm -{ - public DateTime OrderDate; -} -``` - - When an instance of this class is serialized, it might resemble the following. - -```xml - - 12/12/01 - -``` - - For more examples of serialization, see [Examples of XML Serialization](../../../docs/standard/serialization/examples-of-xml-serialization.md). - -## Items That Can Be Serialized - The following items can be serialized using the **XmLSerializer** class: - -- Public read/write properties and fields of public classes. - -- Classes that implement **ICollection** or **IEnumerable**. - - > [!NOTE] - > Only collections are serialized, not public properties. - -- **XmlElement** objects. - -- **XmlNode** objects. - -- **DataSet** objects. - - For more information about serializing or deserializing objects, see [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) and [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md). - -## Advantages of Using XML Serialization - The **XmlSerializer**class gives you complete and flexible control when you serialize an object as XML. If you are creating an XML Web service, you can apply attributes that control serialization to classes and members to ensure that the XML output conforms to a specific schema. - - For example, **XmlSerializer** enables you to: - -- Specify whether a field or property should be encoded as an attribute or an element. - -- Specify an XML namespace to use. - -- Specify the name of an element or attribute if a field or property name is inappropriate. - - Another advantage of XML serialization is that you have no constraints on the applications you develop, as long as the XML stream that is generated conforms to a given schema. Imagine a schema that is used to describe books. It features a title, author, publisher, and ISBN number element. You can develop an application that processes the XML data in any way you want, for example, as a book order, or as an inventory of books. In either case, the only requirement is that the XML stream conforms to the specified XML Schema definition language (XSD) schema. - -## XML Serialization Considerations - The following should be considered when using the **XmlSerializer** class: - -- The Sgen.exe tool is expressly designed to generate serialization assemblies for optimum performance. - -- The serialized data contains only the data itself and the structure of your classes. Type identity and assembly information are not included. - -- Only public properties and fields can be serialized. Properties must have public accessors (get and set methods). If you must serialize non-public data, use the class rather than XML serialization. - -- A class must have a default constructor to be serialized by **XmlSerializer**. - -- Methods cannot be serialized. - -- **XmlSerializer** can process classes that implement **IEnumerable** or **ICollection** differently if they meet certain requirements, as follows. - - A class that implements **IEnumerable** must implement a public **Add** method that takes a single parameter. The **Add** method's parameter must be consistent (polymorphic) with the type returned from the **IEnumerator.Current** property returned from the **GetEnumerator** method. - - A class that implements **ICollection** in addition to **IEnumerable** (such as **CollectionBase**) must have a public **Item** indexed property (an indexer in C#) that takes an integer and it must have a public **Count** property of type **integer**. The parameter passed to the **Add** method must be the same type as that returned from the **Item** property, or one of that type's bases. - - For classes that implement **ICollection**, values to be serialized are retrieved from the indexed **Item** property rather than by calling **GetEnumerator**. Also, public fields and properties are not serialized, with the exception of public fields that return another collection class (one that implements **ICollection**). For an example, see [Examples of XML Serialization](../../../docs/standard/serialization/examples-of-xml-serialization.md). - -## XSD Data Type Mapping - The World Wide Web Consortium (www.w3.org) document titled "XML Schema Part 2: Datatypes" specifies the simple data types that are allowed in an XML Schema definition language (XSD) schema. For many of these (for example, **int** and **decimal**), there is a corresponding data type in the .NET Framework. However, some XML data types do not have a corresponding data type in the .NET Framework (for example, the **NMTOKEN** data type). In such cases, if you use the XML Schema Definition tool ([XML Schema Definition Tool (Xsd.exe)](../../../docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md)) to generate classes from a schema, an appropriate attribute is applied to a member of type string, and its **DataType** property is set to the XML data type name. For example, if a schema contains an element named "MyToken" with the XML data type **NMTOKEN**, the generated class might contain a member as shown in the following example. - -```vb - _ -Public MyToken As String -``` - -```csharp -[XmlElement(DataType = "NMTOKEN")] -public string MyToken; -``` - - Similarly, if you are creating a class that must conform to a specific XML Schema (XSD), you should apply the appropriate attribute and set its **DataType** property to the desired XML data type name. - - For a complete list of type mappings, see the **DataType** property for any of the following attribute classes: - -- - -- - -- - -- - -- - -- - -## See Also - - - - [XML and SOAP Serialization](../../../docs/standard/serialization/xml-and-soap-serialization.md) - [Binary Serialization](../../../docs/standard/serialization/binary-serialization.md) - [Serialization](../../../docs/standard/serialization/index.md) - - [Examples of XML Serialization](../../../docs/standard/serialization/examples-of-xml-serialization.md) - [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) - [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md) +> XML serialization does not convert methods, indexers, private fields, or read-only properties (except read-only collections). To serialize all an object's fields and properties, both public and private, use the instead of XML serialization. + + The central class in XML serialization is the class, and the most important methods in this class are the **Serialize** and **Deserialize** methods. The creates C# files and compiles them into .dll files to perform this serialization. In .NET Framework 2.0, the [XML Serializer Generator Tool (Sgen.exe)](xml-serializer-generator-tool-sgen-exe.md) is designed to generate these serialization assemblies in advance to be deployed with your application and improve startup performance. The XML stream generated by the **XmlSerializer** is compliant with the World Wide Web Consortium (W3C) [XML Schema definition language (XSD) 1.0 recommendation](https://www.w3.org/TR/xslt). Furthermore, the data types generated are compliant with the document titled "XML Schema Part 2: Datatypes." + + The data in your objects is described using programming language constructs like classes, fields, properties, primitive types, arrays, and even embedded XML in the form of **XmlElement** or **XmlAttribute** objects. You have the option of creating your own classes, annotated with attributes, or using the XML Schema Definition tool to generate the classes based on an existing XML Schema. + + If you have an XML Schema, you can run the XML Schema Definition tool to produce a set of classes that are strongly typed to the schema and annotated with attributes. When an instance of such a class is serialized, the generated XML adheres to the XML Schema. Provided with such a class, you can program against an easily manipulated object model while being assured that the generated XML conforms to the XML schema. This is an alternative to using other classes in the .NET Framework, such as the **XmlReader** and **XmlWriter** classes, to parse and write an XML stream. For more information, see [XML Documents and Data](../../../docs/standard/data/xml/index.md). These classes allow you to parse any XML stream. In contrast, use the **XmlSerializer** when the XML stream is expected to conform to a known XML Schema. + + Attributes control the XML stream generated by the **XmlSerializer** class, allowing you to set the XML namespace, element name, attribute name, and so on, of the XML stream. For more information about these attributes and how they control XML serialization, see [Controlling XML Serialization Using Attributes](controlling-xml-serialization-using-attributes.md). For a table of those attributes that are used to control the generated XML, see [Attributes That Control XML Serialization](attributes-that-control-xml-serialization.md). + + The **XmlSerializer** class can further serialize an object and generate an encoded SOAP XML stream. The generated XML adheres to section 5 of the World Wide Web Consortium document titled "Simple Object Access Protocol (SOAP) 1.1." For more information about this process, see [How to: Serialize an Object as a SOAP-Encoded XML Stream](how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md). For a table of the attributes that control the generated XML, see [Attributes That Control Encoded SOAP Serialization](attributes-that-control-encoded-soap-serialization.md). + + The **XmlSerializer** class generates the SOAP messages created by, and passed to, XML Web services. To control the SOAP messages, you can apply attributes to the classes, return values, parameters, and fields found in an XML Web service file (.asmx). You can use both the attributes listed in "Attributes That Control XML Serialization" and "Attributes That Control Encoded SOAP Serialization" because an XML Web service can use either the literal or encoded SOAP style. For more information about using attributes to control the XML generated by an XML Web service, see [XML Serialization with XML Web Services](xml-serialization-with-xml-web-services.md). For more information about SOAP and XML Web services, see [Customizing SOAP Messages](https://msdn.microsoft.com/en-us/subscriptions/index/dkwy2d72\(v=vs.71\).aspx). + +## Security Considerations for XmlSerializer Applications + +When creating an application that uses the **XmlSerializer**, you should be aware of the following items and their implications: + +- The **XmlSerializer** creates C# (.cs) files and compiles them into .dll files in the directory named by the TEMP environment variable; serialization occurs with those DLLs. + + > [!NOTE] + > These serialization assemblies can be generated in advance and signed by using the SGen.exe tool. This does not work a server of Web services. In other words, it is only for client use and for manual serialization. + + The code and the DLLs are vulnerable to a malicious process at the time of creation and compilation. When using a computer running Microsoft Windows NT 4.0 or later, it might be possible for two or more users to share the TEMP directory. Sharing a TEMP directory is dangerous if the two accounts have different security privileges and the higher-privilege account runs an application using the **XmlSerializer**. In this case, one user can breach the computer's security by replacing either the .cs or .dll file that is compiled. To eliminate this concern, always be sure that each account on the computer has its own profile. By default, the TEMP environment variable points to a different directory for each account. + +- If a malicious user sends a continuous stream of XML data to a Web server (a denial of service attack), then the **XmlSerializer** continues to process the data until the computer runs low on resources. + + This kind of attack is eliminated if you are using a computer running Internet Information Services (IIS), and your application is running within IIS. IIS features a gate that does not process streams longer than a set amount (the default is 4 KB). If you create an application that does not use IIS and deserializes with the **XmlSerializer**, you should implement a similar gate that prevents a denial of service attack. + +- The **XmlSerializer** serializes data and runs any code using any type given to it. + + There are two ways in which a malicious object presents a threat. It could run malicious code or it could inject malicious code into the C# file created by the **XmlSerializer**. In the first case, if a malicious object tries to run a destructive procedure, code access security helps prevent any damage from being done. In the second case, there is a theoretical possibility that a malicious object may somehow inject code into the C# file created by the **XmlSerializer**. Although this issue has been examined thoroughly, and such an attack is considered unlikely, you should take the precaution of never serializing data with an unknown and untrusted type. + +- Serialized sensitive data might be vulnerable. + + After the **XmlSerializer**has serialized data, it can be stored as an XML file or other data store. If your data store is available to other processes, or is visible on an intranet or the Internet, the data can be stolen and used maliciously. For example, if you create an application that serializes orders that include credit card numbers, the data is highly sensitive. To help prevent this, always protect the store for your data and take steps to keep it private. + +## Serialization of a Simple Class + +The following code example shows a basic class with a public field. + +```vb +Public Class OrderForm + Public OrderDate As DateTime +End Class +``` + +```csharp +public class OrderForm +{ + public DateTime OrderDate; +} +``` + +When an instance of this class is serialized, it might resemble the following. + +```xml + + 12/12/01 + +``` + +For more examples of serialization, see [Examples of XML Serialization](examples-of-xml-serialization.md). + +## Items That Can Be Serialized + +The following items can be serialized using the **XmLSerializer** class: + +- Public read/write properties and fields of public classes. + +- Classes that implement **ICollection** or **IEnumerable**. + + > [!NOTE] + > Only collections are serialized, not public properties. + +- **XmlElement** objects. + +- **XmlNode** objects. + +- **DataSet** objects. + + For more information about serializing or deserializing objects, see [How to: Serialize an Object](how-to-serialize-an-object.md) and [How to: Deserialize an Object](how-to-deserialize-an-object.md). + +## Advantages of Using XML Serialization + +The **XmlSerializer**class gives you complete and flexible control when you serialize an object as XML. If you are creating an XML Web service, you can apply attributes that control serialization to classes and members to ensure that the XML output conforms to a specific schema. + +For example, **XmlSerializer** enables you to: + +- Specify whether a field or property should be encoded as an attribute or an element. + +- Specify an XML namespace to use. + +- Specify the name of an element or attribute if a field or property name is inappropriate. + +Another advantage of XML serialization is that you have no constraints on the applications you develop, as long as the XML stream that is generated conforms to a given schema. Imagine a schema that is used to describe books. It features a title, author, publisher, and ISBN number element. You can develop an application that processes the XML data in any way you want, for example, as a book order, or as an inventory of books. In either case, the only requirement is that the XML stream conforms to the specified XML Schema definition language (XSD) schema. + +## XML Serialization Considerations + +The following should be considered when using the **XmlSerializer** class: + +- The Sgen.exe tool is expressly designed to generate serialization assemblies for optimum performance. + +- The serialized data contains only the data itself and the structure of your classes. Type identity and assembly information are not included. + +- Only public properties and fields can be serialized. Properties must have public accessors (get and set methods). If you must serialize non-public data, use the class rather than XML serialization. + +- A class must have a default constructor to be serialized by **XmlSerializer**. + +- Methods cannot be serialized. + +- **XmlSerializer** can process classes that implement **IEnumerable** or **ICollection** differently if they meet certain requirements, as follows. + + A class that implements **IEnumerable** must implement a public **Add** method that takes a single parameter. The **Add** method's parameter must be consistent (polymorphic) with the type returned from the **IEnumerator.Current** property returned from the **GetEnumerator** method. + + A class that implements **ICollection** in addition to **IEnumerable** (such as **CollectionBase**) must have a public **Item** indexed property (an indexer in C#) that takes an integer and it must have a public **Count** property of type **integer**. The parameter passed to the **Add** method must be the same type as that returned from the **Item** property, or one of that type's bases. + + For classes that implement **ICollection**, values to be serialized are retrieved from the indexed **Item** property rather than by calling **GetEnumerator**. Also, public fields and properties are not serialized, with the exception of public fields that return another collection class (one that implements **ICollection**). For an example, see [Examples of XML Serialization](examples-of-xml-serialization.md). + +## XSD Data Type Mapping + +The W3C document titled [XML Schema Part 2: Datatypes](https://www.w3.org/TR/xmlschema-2/) specifies the simple data types that are allowed in an XML Schema definition language (XSD) schema. For many of these (for example, **int** and **decimal**), there is a corresponding data type in the .NET Framework. However, some XML data types do not have a corresponding data type in the .NET Framework (for example, the **NMTOKEN** data type). In such cases, if you use the XML Schema Definition tool ([XML Schema Definition Tool (Xsd.exe)](xml-schema-definition-tool-xsd-exe.md)) to generate classes from a schema, an appropriate attribute is applied to a member of type string, and its **DataType** property is set to the XML data type name. For example, if a schema contains an element named "MyToken" with the XML data type **NMTOKEN**, the generated class might contain a member as shown in the following example. + +```vb + _ +Public MyToken As String +``` + +```csharp +[XmlElement(DataType = "NMTOKEN")] +public string MyToken; +``` + +Similarly, if you are creating a class that must conform to a specific XML Schema (XSD), you should apply the appropriate attribute and set its **DataType** property to the desired XML data type name. + +For a complete list of type mappings, see the **DataType** property for any of the following attribute classes: + +- + +- + +- + +- + +- + +- + +## See Also + + + + +[XML and SOAP Serialization](xml-and-soap-serialization.md) +[Binary Serialization](binary-serialization.md) +[Serialization](index.md) + +[Examples of XML Serialization](examples-of-xml-serialization.md) +[How to: Serialize an Object](how-to-serialize-an-object.md) +[How to: Deserialize an Object](how-to-deserialize-an-object.md) \ No newline at end of file diff --git a/docs/standard/serialization/xml-and-soap-serialization.md b/docs/standard/serialization/xml-and-soap-serialization.md index e7fb9c202a6fb..b7e2181ca2913 100644 --- a/docs/standard/serialization/xml-and-soap-serialization.md +++ b/docs/standard/serialization/xml-and-soap-serialization.md @@ -11,75 +11,79 @@ helpviewer_keywords: ms.assetid: 832ac524-21bc-419a-a27b-ca8bfc45840f --- # XML and SOAP Serialization -XML serialization converts (serializes) the public fields and properties of an object, or the parameters and return values of methods, into an XML stream that conforms to a specific XML Schema definition language (XSD) document. XML serialization results in strongly typed classes with public properties and fields that are converted to a serial format (in this case, XML) for storage or transport. - - Because XML is an open standard, the XML stream can be processed by any application, as needed, regardless of platform. For example, XML Web services created using ASP.NET use the class to create XML streams that pass data between XML Web service applications throughout the Internet or on intranets. Conversely, deserialization takes such an XML stream and reconstructs the object. - - XML serialization can also be used to serialize objects into XML streams that conform to the SOAP specification. SOAP is a protocol based on XML, designed specifically to transport procedure calls using XML. - - To serialize or deserialize objects, use the class. To create the classes to be serialized, use the XML Schema Definition tool. - -## In This Section - [Introducing XML Serialization](../../../docs/standard/serialization/introducing-xml-serialization.md) - Provides a general definition of serialization, particularly XML serialization. - - [How to: Serialize an Object](../../../docs/standard/serialization/how-to-serialize-an-object.md) - Provides step-by-step instructions for serializing an object. - - [How to: Deserialize an Object](../../../docs/standard/serialization/how-to-deserialize-an-object.md) - Provides step-by-step instructions for deserializing an object. - - [Examples of XML Serialization](../../../docs/standard/serialization/examples-of-xml-serialization.md) - Provides examples that demonstrate the basics of XML serialization. - - [The XML Schema Definition Tool and XML Serialization](../../../docs/standard/serialization/the-xml-schema-definition-tool-and-xml-serialization.md) - Describes how to use the XML Schema Definition tool to create classes that adhere to a particular XML Schema definition language (XSD) schema, or to generate an XML Schema from a .dll file. - - [Controlling XML Serialization Using Attributes](../../../docs/standard/serialization/controlling-xml-serialization-using-attributes.md) - Describes how to control serialization by using attributes. - - [Attributes That Control XML Serialization](../../../docs/standard/serialization/attributes-that-control-xml-serialization.md) - Lists the attributes that are used to control XML serialization. - - [How to: Specify an Alternate Element Name for an XML Stream](../../../docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md) - Presents an advanced scenario showing how to generate multiple XML streams by overriding the serialization. - - [How to: Control Serialization of Derived Classes](../../../docs/standard/serialization/how-to-control-serialization-of-derived-classes.md) - Provides an example of how to control the serialization of derived classes. - - [How to: Qualify XML Element and XML Attribute Names](../../../docs/standard/serialization/how-to-qualify-xml-element-and-xml-attribute-names.md) - Describes how to define and control the way in which XML namespaces are used in the XML stream. - - [XML Serialization with XML Web Services](../../../docs/standard/serialization/xml-serialization-with-xml-web-services.md) - Explains how XML serialization is used in XML Web services. - - [How to: Serialize an Object as a SOAP-Encoded XML Stream](../../../docs/standard/serialization/how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) - Describes how to use the class to create encoded SOAP XML streams that conform to section 5 of the World Wide Web Consortium (www.w3.org) document titled "Simple Object Access Protocol (SOAP) 1.1." - - [How to: Override Encoded SOAP XML Serialization](../../../docs/standard/serialization/how-to-override-encoded-soap-xml-serialization.md) - Describes the process for overriding XML serialization of objects as SOAP messages. - - [Attributes That Control Encoded SOAP Serialization](../../../docs/standard/serialization/attributes-that-control-encoded-soap-serialization.md) - Lists the attributes that are used to control SOAP-encoded serialization. - - [\ Element](../../../docs/standard/serialization/system-xml-serialization-element.md) - The top-level configuration element for controlling XML serialization. - - [\ Element](../../../docs/standard/serialization/datetimeserialization-element.md) - Controls the serialization mode of objects. - - [\ Element](../../../docs/standard/serialization/schemaimporterextensions-element.md) - Contains types that are used by the class. - - [\ Element for \](../../../docs/standard/serialization/add-element-for-schemaimporterextensions.md) - Adds types that are used by the class. - -## Related Sections - [Advanced Development Technologies](https://msdn.microsoft.com/library/c4a7e341-f0c6-4df4-a74f-223387ac6e4e) - Provides links to more information on sophisticated development tasks and techniques in the .NET Framework. - - [XML Web Services Created Using ASP.NET and XML Web Service Clients](https://msdn.microsoft.com/library/1e64af78-d705-4384-b08d-591a45f4379c) - Provides topics that describe and explain how to program XML Web services using ASP.NET. - -## See Also - [Binary Serialization](../../../docs/standard/serialization/binary-serialization.md) + +XML serialization converts (serializes) the public fields and properties of an object, or the parameters and return values of methods, into an XML stream that conforms to a specific XML Schema definition language (XSD) document. XML serialization results in strongly typed classes with public properties and fields that are converted to a serial format (in this case, XML) for storage or transport. + +Because XML is an open standard, the XML stream can be processed by any application, as needed, regardless of platform. For example, XML Web services created using ASP.NET use the class to create XML streams that pass data between XML Web service applications throughout the Internet or on intranets. Conversely, deserialization takes such an XML stream and reconstructs the object. + +XML serialization can also be used to serialize objects into XML streams that conform to the SOAP specification. SOAP is a protocol based on XML, designed specifically to transport procedure calls using XML. + +To serialize or deserialize objects, use the class. To create the classes to be serialized, use the XML Schema Definition tool. + +## In This Section + +[Introducing XML Serialization](introducing-xml-serialization.md) +Provides a general definition of serialization, particularly XML serialization. + +[How to: Serialize an Object](how-to-serialize-an-object.md) +Provides step-by-step instructions for serializing an object. + +[How to: Deserialize an Object](how-to-deserialize-an-object.md) +Provides step-by-step instructions for deserializing an object. + +[Examples of XML Serialization](examples-of-xml-serialization.md) +Provides examples that demonstrate the basics of XML serialization. + +[The XML Schema Definition Tool and XML Serialization](the-xml-schema-definition-tool-and-xml-serialization.md) +Describes how to use the XML Schema Definition tool to create classes that adhere to a particular XML Schema definition language (XSD) schema, or to generate an XML Schema from a .dll file. + +[Controlling XML Serialization Using Attributes](controlling-xml-serialization-using-attributes.md) +Describes how to control serialization by using attributes. + +[Attributes That Control XML Serialization](attributes-that-control-xml-serialization.md) +Lists the attributes that are used to control XML serialization. + +[How to: Specify an Alternate Element Name for an XML Stream](how-to-specify-an-alternate-element-name-for-an-xml-stream.md) +Presents an advanced scenario showing how to generate multiple XML streams by overriding the serialization. + +[How to: Control Serialization of Derived Classes](how-to-control-serialization-of-derived-classes.md) +Provides an example of how to control the serialization of derived classes. + +[How to: Qualify XML Element and XML Attribute Names](how-to-qualify-xml-element-and-xml-attribute-names.md) +Describes how to define and control the way in which XML namespaces are used in the XML stream. + +[XML Serialization with XML Web Services](xml-serialization-with-xml-web-services.md) +Explains how XML serialization is used in XML Web services. + +[How to: Serialize an Object as a SOAP-Encoded XML Stream](how-to-serialize-an-object-as-a-soap-encoded-xml-stream.md) +Describes how to use the class to create encoded SOAP XML streams that conform to section 5 of the World Wide Web Consortium (W3C) document titled [Simple Object Access Protocol (SOAP) 1.1](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/). + +[How to: Override Encoded SOAP XML Serialization](how-to-override-encoded-soap-xml-serialization.md) +Describes the process for overriding XML serialization of objects as SOAP messages. + +[Attributes That Control Encoded SOAP Serialization](attributes-that-control-encoded-soap-serialization.md) +Lists the attributes that are used to control SOAP-encoded serialization. + +[\ Element](system-xml-serialization-element.md) +The top-level configuration element for controlling XML serialization. + +[\ Element](datetimeserialization-element.md) +Controls the serialization mode of objects. + +[\ Element](schemaimporterextensions-element.md) +Contains types that are used by the class. + +[\ Element for \](add-element-for-schemaimporterextensions.md) +Adds types that are used by the class. + +## Related Sections + +[Advanced Development Technologies](https://msdn.microsoft.com/library/c4a7e341-f0c6-4df4-a74f-223387ac6e4e) +Provides links to more information on sophisticated development tasks and techniques in the .NET Framework. + +[XML Web Services Created Using ASP.NET and XML Web Service Clients](https://msdn.microsoft.com/library/1e64af78-d705-4384-b08d-591a45f4379c) +Provides topics that describe and explain how to program XML Web services using ASP.NET. + +## See Also + +[Binary Serialization](binary-serialization.md) \ No newline at end of file From 5dd0e24cc670a47fd7cc7f60cebf13f80dc1c0a5 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 10 Aug 2018 18:21:01 -0700 Subject: [PATCH 13/13] .NET Framework markdig conversion issues, Part 3 (#6903) * .NET Framework markdig conversion issues, Part 3 * Fixed bad code reference * fix bold formatting --- .../aggregate-canonical-functions.md | 187 +++++++- .../math-canonical-functions.md | 136 +++++- .../data/adonet/ef/mathematical-functions.md | 405 ++++++++++++++++-- .../query-projections-wcf-data-services.md | 48 ++- .../directives-element-net-native.md | 6 +- 5 files changed, 710 insertions(+), 72 deletions(-) diff --git a/docs/framework/data/adonet/ef/language-reference/aggregate-canonical-functions.md b/docs/framework/data/adonet/ef/language-reference/aggregate-canonical-functions.md index 804056b094cd9..177e3a8d3f627 100644 --- a/docs/framework/data/adonet/ef/language-reference/aggregate-canonical-functions.md +++ b/docs/framework/data/adonet/ef/language-reference/aggregate-canonical-functions.md @@ -7,20 +7,179 @@ ms.assetid: 3bcff826-ca90-41b3-a791-04d6ff0e5085 Aggregates are expressions that reduce a series of input values into, for example, a single value. Aggregates are normally used in conjunction with the GROUP BY clause of the SELECT expression, and there are constraints on where they can be used. -The following table shows the aggregate [!INCLUDE[esql](../../../../../../includes/esql-md.md)] canonical functions. - -| Function | Description | -| -------- | ----------- | -| `Avg(expression)` | Returns the average of the non-null values.

**Arguments**

An `Int32`, `Int64`, `Double`, and `Decimal`.

**Return Value**

The type of `expression`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_AVG](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_avg)] [!code-sql[DP EntityServices Concepts#EDM_AVG](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_avg)] | -| `BigCount(expression)` | Returns the size of the aggregate including null and duplicate values.

**Arguments**

Any type.

**Return Value**

An `Int64`.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_BIGCOUNT](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_bigcount)] [!code-sql[DP EntityServices Concepts#EDM_BIGCOUNT](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_bigcount)] | -| `Count(expression)` | Returns the size of the aggregate including null and duplicate values.

**Arguments**

Any type.

**Return Value**

An `Int32`.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_COUNT](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_count)] [!code-sql[DP EntityServices Concepts#EDM_COUNT](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_count)] | -| `Max(expression)` | Returns the maximum of the non-null values.

**Arguments**

A `Byte`, `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, `Decimal`, `DateTime`, `DateTimeOffset`, `Time`, `String`, `Binary`.

**Return Value**

The type of `expression`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_MAX](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_max)] [!code-sql[DP EntityServices Concepts#EDM_MAX](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_max)] | -| `Min(expression)` | Returns the minimum of the non-null values.

**Arguments**

A `Byte`, `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, `Decimal`, `DateTime`, `DateTimeOffset`, `Time`, `String`, `Binary`.

**Return Value**

The type of `expression`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_MIN](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_min)] [!code-sql[DP EntityServices Concepts#EDM_MIN](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_min)] | -| `StDev(expression)` | Returns the standard deviation of the non-null values.

**Arguments**

An `Int32`, `Int64`, `Double`, `Decimal`.

**Return Value**

A `Double`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_STDEV](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_stdev)] [!code-sql[DP EntityServices Concepts#EDM_STDEV](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_stdev)] | -| `StDevP(expression)` | Returns the standard deviation for the population of all values.

**Arguments**

An `Int32`, `Int64`, `Double`, `Decimal`.

**Return Value**

A `Double`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_STDEVP](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_stdevp)] [!code-sql[DP EntityServices Concepts#EDM_STDEVP](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_stdevp)] | -| `Sum(expression)` | Returns the sum of the non-null values.

**Arguments**

An `Int32`, `Int64`, `Double`, `Decimal`.

**Return Value**

A `Double`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_SUM](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_sum)] [!code-sql[DP EntityServices Concepts#EDM_SUM](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_sum)] | -| `Var(expression)` | Returns the variance of all non-null values.

**Arguments**

An `Int32`, `Int64`, `Double`, `Decimal`.

**Return Value**

A `Double`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_VAR](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_var)] [!code-sql[DP EntityServices Concepts#EDM_VAR](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_var)] | -| `VarP(expression)` | Returns the variance for the population of all non-null values.

**Arguments**

An `Int32`, `Int64`, `Double`, `Decimal`.

**Return Value**

A `Double`. `Null`, if all input values are `null` values.

**Example**[!code-csharp[DP EntityServices Concepts#EDM_VARP](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_varp)] [!code-sql[DP EntityServices Concepts#EDM_VARP](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_varp)] | +## Aggegate Entity SQL canonical functions + +The following are the aggregate Entity SQL canonical functions. + +### Avg(expression) + +Returns the average of the non-null values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, and `Decimal`. + +**Return Value** + +The type of `expression`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_AVG](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_avg)] +[!code-sql[DP EntityServices Concepts#EDM_AVG](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_avg)] + +### BigCount(expression) + +Returns the size of the aggregate including null and duplicate values. + +**Arguments** + +Any type. + +**Return Value** + +An `Int64`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_BIGCOUNT](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_bigcount)] +[!code-sql[DP EntityServices Concepts#EDM_BIGCOUNT](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_bigcount)] + +### Count(expression) + +Returns the size of the aggregate including null and duplicate values. + +**Arguments** + +Any type. + +**Return Value** + +An `Int32`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_COUNT](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_count)] +[!code-sql[DP EntityServices Concepts#EDM_COUNT](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_count)] + +### Max(expression) + +Returns the maximum of the non-null values. + +**Arguments** + +A `Byte`, `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, `Decimal`, `DateTime`, `DateTimeOffset`, `Time`, `String`, `Binary`. + +**Return Value** + +The type of `expression`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_MAX](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_max)] +[!code-sql[DP EntityServices Concepts#EDM_MAX](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_max)] + +### Min(expression) + +Returns the minimum of the non-null values. + +**Arguments** + +A `Byte`, `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, `Decimal`, `DateTime`, `DateTimeOffset`, `Time`, `String`, `Binary`. + +**Return Value** + +The type of `expression`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_MIN](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_min)] +[!code-sql[DP EntityServices Concepts#EDM_MIN](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_min)] + +### StDev(expression) + +Returns the standard deviation of the non-null values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, `Decimal`. + +**Return Value** + +A `Double`. `Null`, if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_STDEV](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_stdev)] +[!code-sql[DP EntityServices Concepts#EDM_STDEV](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_stdev)] + +### StDevP(expression) + +Returns the standard deviation for the population of all values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, `Decimal`. + +**Return Value** + +A `Double`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_STDEVP](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_stdevp)] +[!code-sql[DP EntityServices Concepts#EDM_STDEVP](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_stdevp)] + +### Sum(expression) + +Returns the sum of the non-null values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, `Decimal`. + +**Return Value** + +A `Double`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_SUM](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_sum)] +[!code-sql[DP EntityServices Concepts#EDM_SUM](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_sum)] + +### Var(expression) + +Returns the variance of all non-null values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, `Decimal`. + +**Return Value** + +A `Double`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_VAR](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_var)] +[!code-sql[DP EntityServices Concepts#EDM_VAR](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_var)] + +### VarP(expression) + +Returns the variance for the population of all non-null values. + +**Arguments** + +An `Int32`, `Int64`, `Double`, `Decimal`. + +**Return Value** + +A `Double`, or `null` if all input values are `null` values. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_VARP](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_varp)] +[!code-sql[DP EntityServices Concepts#EDM_VARP](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_varp)] Equivalent functionality is available in the Microsoft SQL Client Managed Provider. For more information, see [SqlClient for Entity Framework Functions](../../../../../../docs/framework/data/adonet/ef/sqlclient-for-ef-functions.md). diff --git a/docs/framework/data/adonet/ef/language-reference/math-canonical-functions.md b/docs/framework/data/adonet/ef/language-reference/math-canonical-functions.md index 938db6e0172e1..50a4ebb097489 100644 --- a/docs/framework/data/adonet/ef/language-reference/math-canonical-functions.md +++ b/docs/framework/data/adonet/ef/language-reference/math-canonical-functions.md @@ -4,19 +4,131 @@ ms.date: "03/30/2017" ms.assetid: 6f6cddc6-b561-4ebe-84b6-841ef5b4113b --- # Math Canonical Functions -[!INCLUDE[esql](../../../../../../includes/esql-md.md)] includes math canonical functions. + +Entity SQL includes the following math canonical functions: - The following table shows the math [!INCLUDE[esql](../../../../../../includes/esql-md.md)] canonical functions. - -|Function|Description| -|--------------|-----------------| -|`Abs(value)`|Returns the absolute value of `value`.

**Arguments**

An `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, and `Decimal`.

**Return Value**

The type of `value`.

**Example**

`Abs(-2)`| -|`Ceiling(value)`|Returns the smallest integer that is not less than `value`.

**Arguments**

A `Single`, `Double`, and `Decimal`.

**Return Value**

The type of `value`.

**Example**

[!code-csharp[DP EntityServices Concepts#EDM_CEILING](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_ceiling)]

[!code-sql[DP EntityServices Concepts#EDM_CEILING](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_ceiling)]| -|`Floor(value)`|Returns the largest integer that is not greater than `value`.

**Arguments**

A `Single`, `Double`, and `Decimal`.

**Return Value**

The type of `value`.

**Example**

[!code-csharp[DP EntityServices Concepts#EDM_FLOOR](../../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_floor)]

[!code-sql[DP EntityServices Concepts#EDM_FLOOR](../../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_floor)]| -|`Power(value, exponent)`|Returns the result of the specified `value` to the specified `exponent`.

**Arguments**

`value`: An `Int32, Int64, Double`, or `Decimal`.

`exponent`: An `Int64`, `Double`, or `Decimal`.

**Return Value**

The type of `value`.

**Example**

`Power(748.58,2)`| -|`Round(value)`|Returns the integer portion of `value`, rounded to the nearest integer.

**Arguments**

A `Single`, `Double`, and `Decimal`.

**Return Value**

The type of `value`.

**Example**

`Round(748.58)`| -|`Round(value, digits)`|Returns the `value`, rounded to the nearest specified `digits`.

**Arguments**

`value`: `Double` or `Decimal`.

`digits`: `Int16` or `Int32`.

**Return Value**

The type of `value`.

**Example**

`Round(748.58,1)`| -|`Truncate(value, digits)`|Returns the `value`, truncated to the nearest specified `digits`.

**Arguments**

`value`: `Double` or `Decimal`.

`digits`: `Int16` or `Int32`.

**Return Value**

The type of `value`.

**Example**

`Truncate(748.58,1)`| +## Abs(value) + +Returns the absolute value of `value`. + +**Arguments** + +An `Int16`, `Int32`, `Int64`, `Byte`, `Single`, `Double`, and `Decimal`. + +**Return Value** + +The type of `value`. + +**Example** + +`Abs(-2)` + +## Ceiling(value) + +Returns the smallest integer that is not less than `value`. + +**Arguments** + +A `Single`, `Double`, and `Decimal`. + +**Return Value** + +The type of `value`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_CEILING](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_ceiling)] +[!code-sql[DP EntityServices Concepts#EDM_CEILING](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_ceiling)] + +## Floor(value) + +Returns the largest integer that is not greater than `value`. + +**Arguments** + +A `Single`, `Double`, and `Decimal`. + +**Return Value** + +The type of `value`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#EDM_FLOOR](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#edm_floor)] +[!code-sql[DP EntityServices Concepts#EDM_FLOOR](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#edm_floor)] + +## Power(value, exponent) + +Returns the result of the specified `value` to the specified `exponent`. + +**Arguments** + +| | | +|--|--| +|`value` | An `Int32, Int64, Double`, or `Decimal`. | +|`exponent` | An `Int64`, `Double`, or `Decimal`. | + +**Return Value** + +The type of `value`. + +**Example** + +`Power(748.58,2)` + +## Round(value) + +Returns the integer portion of `value`, rounded to the nearest integer. + +**Arguments** + +A `Single`, `Double`, and `Decimal`. + +**Return Value** + +The type of `value`. + +**Example** + +`Round(748.58)` + +## Round(value, digits) + +Returns the `value`, rounded to the nearest specified `digits`. + +**Arguments** + +| | | +|--|--| +|`value`|`Double` or `Decimal`.| +|`digits`|`Int16` or `Int32`.| + +**Return Value** + +The type of `value`. + +**Example** + +`Round(748.58,1)` + +## Truncate(value, digits) + +Returns the `value`, truncated to the nearest specified `digits`. + +**Arguments** + +| | | +|--|--| +|`value`|`Double` or `Decimal`.| +|`digits`|`Int16` or `Int32`.| + +**Return Value** + +The type of `value`. + +**Example** + +`Truncate(748.58,1)` These functions will return `null` if given `null` input. diff --git a/docs/framework/data/adonet/ef/mathematical-functions.md b/docs/framework/data/adonet/ef/mathematical-functions.md index 8a54dc9d2974b..8bd6dbb6a8226 100644 --- a/docs/framework/data/adonet/ef/mathematical-functions.md +++ b/docs/framework/data/adonet/ef/mathematical-functions.md @@ -4,39 +4,382 @@ ms.date: "03/30/2017" ms.assetid: b040c7cb-156d-40f2-9152-61065b18148c --- # Mathematical Functions + The .NET Framework Data Provider for SQL Server (SqlClient) provides math functions that perform calculations on input values that are provided as arguments, and return a numeric value result. These functions are in the SqlServer namespace, which is available when you use SqlClient. A provider's namespace property allows the Entity Framework to discover which prefix is used by this provider for specific constructs, such as types and functions.The following table describes the SqlClient math functions. -|Function|Description| -|--------------|-----------------| -|`ABS(expression)`|Performs the absolute value function.

**Arguments**

`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

**Return Value**

The absolute value of the specified expression.

**Example**

`SqlServer.ABS(-2)`| -|`ACOS(expression)`|Returns the arccosine value of the specified expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.ACOS(.9)`| -|`ASIN(expression)`|Returns the arcsine value of the specified expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.ASIN(.9)`| -|`ATAN(expression)`|Returns the arctangent value of the specified numeric expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.ATAN(9)`| -|`ATN2(expression, expression)`|Returns the angle, in radians, whose tangent is between the two specified numeric expressions.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.ATN2(9, 8)`| -|`CEILING(expression)`|Converts the specified expression to the smallest integer that is greater than or equal to it.

**Arguments**

`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

**Return Value**

An `Int32`, `Int64`, `Double`, or `Decimal`.

**Example**

[!code-csharp[DP EntityServices Concepts#SQLSERVER_CEILING](../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#sqlserver_ceiling)]

[!code-sql[DP EntityServices Concepts#SQLSERVER_CEILING](../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#sqlserver_ceiling)]| -|`COS(expression)`|Calculates the trigonometric cosine of the specified angle in radians.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.COS(45)`| -|`COT(expression)`|Calculates the trigonometric cotangent of the specified angle in radians.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.COT(60)`| -|`DEGREES(radians)`|Returns the corresponding angle in degrees.

**Arguments**

`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

**Return Value**

An `Int32`, `Int64`, `Double`, or `Decimal`.

**Example**

`SqlServer.DEGREES(3.1)`| -|`EXP(expression)`|Calculates the exponential value of a specified numeric expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.EXP(1)`| -|`FLOOR(expression)`|Converts the specified expression to the largest integer less than or equal to it.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

[!code-csharp[DP EntityServices Concepts#SQLSERVER_FLOOR](../../../../../samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#sqlserver_floor)]

[!code-sql[DP EntityServices Concepts#SQLSERVER_FLOOR](../../../../../samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#sqlserver_floor)]| -|`LOG(expression)`|Calculates the natural logarithm of the specified `float` expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.LOG(100)`| -|`LOG10(expression)`|Returns the base-10 logarithm of the specified `Double` expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.LOG10(100)`| -|`PI()`|Returns the constant value of pi as a `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.PI()`| -|`POWER(numeric_expression, power_expression)`|Calculates the value of a specified expression to a specified power.

**Arguments**

`numeric_expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

`power_expression`: A `Double` that represents the power to which to raise the `numeric_expression`.

**Return Value**

The value of the specified `numeric_expression` to the specified `power_expression`.

**Example**

`SqlServer.POWER(2,7)`| -|`RADIANS(expression)`|Converts degrees to radians.

**Arguments**

`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

**Return Value**

An `Int32`, `Int64`,

`Double`, or

`Decimal`.

**Example**

`SqlServer.RADIANS(360.0)`| -|`RAND(`[seed]`)`|Returns a random value from 0 through 1.

**Arguments**

Retruns the seed value as an `Int32`. If the seed is not specified, the SQL Server Database Engine assigns a seed value at random. For a specified seed value, the result returned is always the same.

**Return Value**

A random `Double` value from 0 through 1.

**Example**

`SqlServer.RAND()`| -|`ROUND(numeric_expression, length[,function])`|Returns a numeric expression, rounded to the specified length or precision.

**Arguments**

`numeric_expression`: An `Int32`, `Int64`, `Double`, or `Decimal`.

`length`: An `Int32` that represents the precision to which `numeric_expression` is to be rounded. When `length` is a positive number, `numeric_expression` is rounded to the number of decimal positions specified by `length`. When `length` is a negative number, `numeric_expression` is rounded on the left side of the decimal point, as specified by `length`.

`function`:(optional) An `Int32` that represents the type of operation to perform. When function is omitted or has a value of 0 (default), `numeric_expression` is rounded. When a value other than 0 is specified, `numeric_expression` is truncated.

**Return Value**

The value of the specified `numeric_expression` to the specified `power_expression`.

**Example**

`SqlServer.ROUND(748.58, -3)`| -|`SIGN(expression)`|Returns the positive (+1), zero (0), or negative (-1) sign of the specified expression.

**Arguments**

`expression`: `Int32`, `Int64`, `Double`, or `Decimal`

**Return Value**

An `Int32`, `Int64`, `Double`, or `Decimal`.

**Example**

`SqlServer.SIGN(-10)`| -|`SIN(expression)`|Calculates the trigonometric sine of the specified angle in radians, and returns a `Double` expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.SIN(20)`| -|`SQRT(expression)`|Returns the square root of the specified expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.SQRT(3600)`| -|`SQUARE(expression)`|Returns the square of the specified expression.

**Arguments**

`expression`: A `Double`.

**Return Value**

A `Double`.

**Example**

`SqlServer.SQUARE(25)`| -|`TAN(expression)`|Calculates the tangent of a specified expression.

**Arguments**

`expression`: `Double`

**Return Value**

`Double`

**Example**

`SqlServer.TAN(45.0)`| +## ABS(expression) + +Performs the absolute value function. + +**Arguments** + +`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Return Value** + +The absolute value of the specified expression. + +**Example** + +`SqlServer.ABS(-2)` + +## ACOS(expression) + +Returns the arccosine value of the specified expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.ACOS(.9)` + +## ASIN(expression) + +Returns the arcsine value of the specified expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.ASIN(.9)` + +## ATAN(expression) + +Returns the arctangent value of the specified numeric expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.ATAN(9)` + +## ATN2(expression, expression) + +Returns the angle, in radians, whose tangent is between the two specified numeric expressions. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.ATN2(9, 8)` + +## CEILING(expression) + +Converts the specified expression to the smallest integer that is greater than or equal to it. + +**Arguments** + +`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Return Value** + +An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#SQLSERVER_CEILING](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#sqlserver_ceiling)] +[!code-sql[DP EntityServices Concepts#SQLSERVER_CEILING](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#sqlserver_ceiling)] + +## COS(expression) + +Calculates the trigonometric cosine of the specified angle in radians. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.COS(45)` + +## COT(expression) + +Calculates the trigonometric cotangent of the specified angle in radians. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.COT(60)` - For more information about the mathematical functions that SqlClient supports, see the documentation for the SQL Server version that you specified in the SqlClient provider manifest: +## DEGREES(radians) + +Returns the corresponding angle in degrees. + +**Arguments** + +`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Return Value** + +An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Example** + +`SqlServer.DEGREES(3.1)` + +## EXP(expression) + +Calculates the exponential value of a specified numeric expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** `SqlServer.EXP(1)` + +## FLOOR(expression) + +Converts the specified expression to the largest integer less than or equal to it. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +[!code-csharp[DP EntityServices Concepts#SQLSERVER_FLOOR](~/samples/snippets/csharp/VS_Snippets_Data/dp entityservices concepts/cs/entitysql.cs#sqlserver_floor)] +[!code-sql[DP EntityServices Concepts#SQLSERVER_FLOOR](~/samples/snippets/tsql/VS_Snippets_Data/dp entityservices concepts/tsql/entitysql.sql#sqlserver_floor)] + +## LOG(expression) + +Calculates the natural logarithm of the specified `float` expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.LOG(100)` + +## LOG10(expression) + +Returns the base-10 logarithm of the specified `Double` expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.LOG10(100)` + +## PI() + +Returns the constant value of pi as a `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.PI()` + +## POWER(numeric_expression, power_expression) + +Calculates the value of a specified expression to a specified power. + +**Arguments** + +| | | +|--|--| +|`numeric_expression`| An `Int32`, `Int64`, `Double`, or `Decimal`.| +|`power_expression`| A `Double` that represents the power to which to raise the `numeric_expression`.| + +**Return Value** + +The value of the specified `numeric_expression` to the specified `power_expression`. + +**Example** + +`SqlServer.POWER(2,7)` + +## RADIANS(expression) + +Converts degrees to radians. + +**Arguments** + +`expression`: An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Return Value** + +An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Example** + +`SqlServer.RADIANS(360.0)` + +## RAND([seed]) + +Returns a random value from 0 through 1. + +**Arguments** + +The seed value as an `Int32`. If the seed is not specified, the SQL Server Database Engine assigns a seed value at random. For a specified seed value, the result returned is always the same. + +**Return Value** + +A random `Double` value from 0 through 1. + +**Example** + +`SqlServer.RAND()` -|SQL Server 2000|SQL Server 2005|SQL Server 2008| -|---------------------|---------------------|---------------------| -|[Mathematical Functions (Transact-SQL)](http://go.microsoft.com/fwlink/?LinkId=115913)|[Mathematical Functions (Transact-SQL)](http://go.microsoft.com/fwlink/?LinkId=115911)|[Mathematical Functions (Transact-SQL)](http://go.microsoft.com/fwlink/?LinkId=115912)| +## ROUND(numeric_expression, length[,function]) + +Returns a numeric expression, rounded to the specified length or precision. + +**Arguments** + +| | | +|--|--| +|`numeric_expression`| An `Int32`, `Int64`, `Double`, or `Decimal`. +|`length`| An `Int32` that represents the precision to which `numeric_expression` is to be rounded. When `length` is a positive number, `numeric_expression` is rounded to the number of decimal positions specified by `length`. When `length` is a negative number, `numeric_expression` is rounded on the left side of the decimal point, as specified by `length`.| +|`function` | Optional. An `Int32` that represents the type of operation to perform. When function is omitted or has a value of 0 (default), `numeric_expression` is rounded. When a value other than 0 is specified, `numeric_expression` is truncated. | + +**Return Value** + +The value of the specified `numeric_expression` to the specified `power_expression`. + +**Example** + +`SqlServer.ROUND(748.58, -3)` + +## SIGN(expression) + +Returns the positive (+1), zero (0), or negative (-1) sign of the specified expression. + +**Arguments** + +`expression`: `Int32`, `Int64`, `Double`, or `Decimal` + +**Return Value** + +An `Int32`, `Int64`, `Double`, or `Decimal`. + +**Example** + +`SqlServer.SIGN(-10)` + +## SIN(expression) + +Calculates the trigonometric sine of the specified angle in radians, and returns a `Double` expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** `SqlServer.SIN(20)` + +## SQRT(expression) + +Returns the square root of the specified expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** `SqlServer.SQRT(3600)` + +## SQUARE(expression) + +Returns the square of the specified expression. + +**Arguments** + +`expression`: A `Double`. + +**Return Value** + +A `Double`. + +**Example** + +`SqlServer.SQUARE(25)` + +## TAN(expression) + +Calculates the tangent of a specified expression. + +**Arguments** + +`expression`: `Double` + +**Return Value** + +`Double` + +**Example** + +`SqlServer.TAN(45.0)` -## See Also - [SqlClient for Entity Framework Functions](../../../../../docs/framework/data/adonet/ef/sqlclient-for-ef-functions.md) +## See also + +For more information about the mathematical functions that SqlClient supports, see the documentation for the SQL Server version that you specified in the SqlClient provider manifest: + +**SQL Server 2005:** [Mathematical Functions (Transact-SQL)](https://docs.microsoft.com/previous-versions/sql/sql-server-2005/ms177516(v=sql.90)) +**SQL Server 2008:** [Mathematical Functions (Transact-SQL)](https://docs.microsoft.com/previous-versions/sql/sql-server-2008/ms177516(v=sql.100)) +**SQL Server 2012 and later:** [Mathematical Functions (Transact-SQL)](/sql/t-sql/functions/mathematical-functions-transact-sql?view=sql-server-2017) + + [SqlClient for Entity Framework Functions](sqlclient-for-ef-functions.md) diff --git a/docs/framework/data/wcf/query-projections-wcf-data-services.md b/docs/framework/data/wcf/query-projections-wcf-data-services.md index 9e2bc22c4c0da..8d8118b4590d1 100644 --- a/docs/framework/data/wcf/query-projections-wcf-data-services.md +++ b/docs/framework/data/wcf/query-projections-wcf-data-services.md @@ -41,8 +41,8 @@ Projection provides a mechanism in the [!INCLUDE[ssODataFull](../../../../includ ### Creating Projected Types The following example uses an anonymous LINQ query that projects the address-related properties of the `Customers` type into a new `CustomerAddress` type, which is defined on the client and is attributed as an entity type: - [!code-csharp[Astoria Northwind Client#SelectCustomerAddressSpecific](../../../../samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#selectcustomeraddressspecific)] - [!code-vb[Astoria Northwind Client#SelectCustomerAddressSpecific](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#selectcustomeraddressspecific)] + [!code-csharp[Astoria Northwind Client#SelectCustomerAddressSpecific](~/samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#selectcustomeraddressspecific)] + [!code-vb[Astoria Northwind Client#SelectCustomerAddressSpecific](~/samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#selectcustomeraddressspecific)] In this example, the object initializer pattern is used to create a new instance of the `CustmerAddress` type instead of calling a constructor. Constructors are not supported when projecting into entity types, but they can be used when projecting into non-entity and anonymous types. Because `CustomerAddress` is an entity type, changes can be made and sent back to the data service. @@ -50,16 +50,40 @@ Projection provides a mechanism in the [!INCLUDE[ssODataFull](../../../../includ The settings of the are used for identity resolution during query projection. This means that if an instance of the `Customer` type already exists in the , an instance of `CustomerAddress` with the same identity will follow the identity resolution rules set by the - The following table describes the behaviors when projecting results into entity and non-entity types: - -|Action|Entity Type|Non-Entity Type| -|------------|-----------------|----------------------| -|Creating a new projected instance by using initializers, as in the following example:

[!code-csharp[Astoria Northwind Client#ProjectWithInitializer](../../../../samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithinitializer)] - [!code-vb[Astoria Northwind Client#ProjectWithInitializer](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithinitializer)]|Supported|Supported| -|Creating a new projected instance by using constructors, as in the following example:

[!code-csharp[Astoria Northwind Client#ProjectWithConstructor](../../../../samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithconstructor)] - [!code-vb[Astoria Northwind Client#ProjectWithConstructor](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithconstructor)]|A is raised.|Supported| -|Using projection to transform a property value, as in the following example:

[!code-csharp[Astoria Northwind Client#ProjectWithTransform](../../../../samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithtransform)] - [!code-vb[Astoria Northwind Client#ProjectWithTransform](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithtransform)]

This transformation is not supported for entity types because it can lead to confusion and potentially overwriting the data in the data source that belongs to another entity.|A is raised.|Supported| +The following describes the behaviors when projecting results into entity and non-entity types: + +**Creating a new projected instance by using initializers** + +- Example: + + [!code-csharp[Astoria Northwind Client#ProjectWithInitializer](~/samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithinitializer)] + [!code-vb[Astoria Northwind Client#ProjectWithInitializer](~/samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithinitializer)] + +- Entity type: Supported + +- Non-entity type: Supported + +**Creating a new projected instance by using constructors** + +- Example: + + [!code-csharp[Astoria Northwind Client#ProjectWithConstructor](~/samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithconstructor)] + [!code-vb[Astoria Northwind Client#ProjectWithConstructor](~/samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithconstructor)] + +- Entity type: A is raised. + +- Non-entity type: Supported + +**Using projection to transform a property value** + +- Example: + + [!code-csharp[Astoria Northwind Client#ProjectWithTransform](~/samples/snippets/csharp/VS_Snippets_Misc/astoria northwind client/cs/source.cs#projectwithtransform)] + [!code-vb[Astoria Northwind Client#ProjectWithTransform](~/samples/snippets/visualbasic/VS_Snippets_Misc/astoria northwind client/vb/source.vb#projectwithtransform)] + +- Entity type: This transformation is not supported for entity types because it can lead to confusion and potentially overwriting the data in the data source that belongs to another entity. A is raised. + +- Non-entity type: Supported ## Projection Considerations diff --git a/docs/framework/net-native/directives-element-net-native.md b/docs/framework/net-native/directives-element-net-native.md index ea37415e37e6b..b39f16110c890 100644 --- a/docs/framework/net-native/directives-element-net-native.md +++ b/docs/framework/net-native/directives-element-net-native.md @@ -6,14 +6,14 @@ author: "rpetrusha" ms.author: "ronpet" --- # <Directives> Element (.NET Native) -The root element in every runtime directives file for [!INCLUDE[net_native](../../../includes/net-native-md.md)]. +The root element in every runtime directives file for .NET Native. - **\** + `` ## Syntax ```xml - + ```