diff --git a/docs/architecture/blazor-for-web-forms-developers/data.md b/docs/architecture/blazor-for-web-forms-developers/data.md index 4cf4807f32270..a709e91de820d 100644 --- a/docs/architecture/blazor-for-web-forms-developers/data.md +++ b/docs/architecture/blazor-for-web-forms-developers/data.md @@ -1,7 +1,7 @@ --- title: Data access and management description: Learn how to access and handle data in ASP.NET Web Forms and Blazor. -author: csharpfritz +author: csharpfritz ms.author: jefritz no-loc: [Blazor] ms.date: 04/11/2022 @@ -48,7 +48,7 @@ public class Product } ``` -Product has a primary key and three additional fields that would be created in our database: +Product has a primary key and three additional fields that would be created in our database: - EF will identify the `Id` property as a primary key by convention. - `Name` will be stored in a column configured for text storage. The `[Required]` attribute decorating this property will add a `not null` constraint to help enforce this declared behavior of the property. @@ -105,9 +105,9 @@ When ASP.NET was first released, SOAP services were the preferred way for web se builder.Services.AddHttpClient("github", client => { client.BaseAddress = new Uri("http://api.github.com/"); - // Github API versioning + // GitHub API versioning client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json"); - // Github requires a user-agent + // GitHub requires a user-agent client.DefaultRequestHeaders.Add("User-Agent", "BlazorWebForms-Sample"); }); ``` diff --git a/docs/architecture/maui/unit-testing.md b/docs/architecture/maui/unit-testing.md index fbfffa6a40239..b2e8bfdac5bca 100644 --- a/docs/architecture/maui/unit-testing.md +++ b/docs/architecture/maui/unit-testing.md @@ -14,7 +14,7 @@ Multi-platform apps experience problems similar to both desktop and web-based ap A unit test takes a small unit of the app, typically a method, isolates it from the remainder of the code, and verifies that it behaves as expected. Its goal is to check that each unit of functionality performs as expected, so errors don't propagate throughout the app. Detecting a bug where it occurs is more efficient than observing the effect of a bug indirectly at a secondary point of failure. -Unit testing has the most significant effect on code quality when it's an integral part of the software development workflow. Unit tests can act as design documentation and functional specifications for an application. As soon as a method has been written, unit tests should be written that verify the method's behavior in response to standard, boundary, and incorrect input data cases and check any explicit or implicit assumptions made by the code. Alternatively, with test-driven development, unit tests are written before the code. For more information on test-driven development and how to implement it, see [Walkthrough: Test-driven development using Test Explorer.](/visualstudio/test/quick-start-test-driven-development-with-test-explorer) +Unit testing has the most significant effect on code quality when it's an integral part of the software development workflow. Unit tests can act as design documentation and functional specifications for an application. As soon as a method has been written, unit tests should be written that verify the method's behavior in response to standard, boundary, and incorrect input data cases and check any explicit or implicit assumptions made by the code. Alternatively, with test-driven development, unit tests are written before the code. For more information on test-driven development and how to implement it, see [Walkthrough: Test-driven development using Test Explorer.](/visualstudio/test/quick-start-test-driven-development-with-test-explorer). > [!NOTE] > Unit tests are very effective against regression. That is, functionality that used to work, but has been disturbed by a faulty update. diff --git a/docs/architecture/microservices/container-docker-introduction/docker-defined.md b/docs/architecture/microservices/container-docker-introduction/docker-defined.md index b57e2e5bf4db6..5ae1ee3ed9a95 100644 --- a/docs/architecture/microservices/container-docker-introduction/docker-defined.md +++ b/docs/architecture/microservices/container-docker-introduction/docker-defined.md @@ -70,7 +70,7 @@ The system is simple: So, simplifying, that's the core idea of Docker. -In Docker, each layer is the resulting set of changes that happen to the filesystem after executing a command, such as, installing a program. +In Docker, each layer is the resulting set of changes that happen to the filesystem after executing a command, such as installing a program. So, when you "look" at the filesystem after the layer has been copied, you see all the files, included in the layer when the program was installed. diff --git a/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md b/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md index 6820b6f857021..ecf4af6429e66 100644 --- a/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md +++ b/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md @@ -1,6 +1,6 @@ --- title: Use IHttpClientFactory to implement resilient HTTP requests -description: Learn how to use IHttpClientFactory, available since .NET Core 2.1, for creating `HttpClient` instances, making it easy for you to use it in your applications. +description: Learn how to use IHttpClientFactory, available since .NET Core 2.1, for creating `HttpClient` instances, making it easy for you to use it in your applications. ms.date: 01/13/2021 --- # Use IHttpClientFactory to implement resilient HTTP requests @@ -54,7 +54,7 @@ There are several ways that you can use `IHttpClientFactory` in your application For the sake of brevity, this guidance shows the most structured way to use `IHttpClientFactory`, which is to use Typed Clients (Service Agent pattern). However, all options are documented and are currently listed in this [article covering the `IHttpClientFactory` usage](/aspnet/core/fundamentals/http-requests#consumption-patterns). > [!NOTE] -> If your app requires cookies, it might be better to avoid using in your app. For alternative ways of managing clients, see [Guidelines for using HTTP clients](../../../fundamentals/networking/http/httpclient-guidelines.md) +> If your app requires cookies, it might be better to avoid using in your app. For alternative ways of managing clients, see [Guidelines for using HTTP clients](../../../fundamentals/networking/http/httpclient-guidelines.md). ## How to use Typed Clients with IHttpClientFactory @@ -191,19 +191,19 @@ Up to this point, the above code snippet only shows the example of performing re ## Additional resources -- **HttpClient guidelines for .NET** +- **HttpClient guidelines for .NET** [https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient-guidelines](../../../fundamentals/networking/http/httpclient-guidelines.md) -- **Using HttpClientFactory in .NET** +- **Using HttpClientFactory in .NET** [https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory](../../../core/extensions/httpclient-factory.md) -- **Using HttpClientFactory in ASP.NET Core** +- **Using HttpClientFactory in ASP.NET Core** [https://learn.microsoft.com/aspnet/core/fundamentals/http-requests](/aspnet/core/fundamentals/http-requests) -- **HttpClientFactory source code in the `dotnet/runtime` GitHub repository** +- **HttpClientFactory source code in the `dotnet/runtime` GitHub repository** -- **Polly (.NET resilience and transient-fault-handling library)** +- **Polly (.NET resilience and transient-fault-handling library)** >[!div class="step-by-step"] diff --git a/docs/framework/data/adonet/dataset-datatable-dataview/security-guidance.md b/docs/framework/data/adonet/dataset-datatable-dataview/security-guidance.md index 05498859c1596..800c94b97e3db 100644 --- a/docs/framework/data/adonet/dataset-datatable-dataview/security-guidance.md +++ b/docs/framework/data/adonet/dataset-datatable-dataview/security-guidance.md @@ -441,11 +441,11 @@ public class MyClass } ``` -In these cases, the threat model and security guarantees are the same as the [DataSet.ReadXml and DataTable.ReadXml section](#dsrdtr) +In these cases, the threat model and security guarantees are the same as the [DataSet.ReadXml and DataTable.ReadXml section](#dsrdtr). ## Deserialize a DataSet or DataTable via JsonConvert -The popular third-party Newtonsoft library [Json.NET](https://www.newtonsoft.com/json) can be used to deserialize `DataSet` and `DataTable` instances, as shown in the following code: +The third-party Newtonsoft library [Json.NET](https://www.newtonsoft.com/json) can be used to deserialize `DataSet` and `DataTable` instances, as shown in the following code: ```csharp using System.Data; diff --git a/docs/framework/data/adonet/ef/language-reference/entity-sql-language.md b/docs/framework/data/adonet/ef/language-reference/entity-sql-language.md index 7f7ebdc27ba99..8f1b46cbccd92 100644 --- a/docs/framework/data/adonet/ef/language-reference/entity-sql-language.md +++ b/docs/framework/data/adonet/ef/language-reference/entity-sql-language.md @@ -10,7 +10,7 @@ Entity SQL is a storage-independent query language that is similar to SQL. Entit - When a query must be dynamically constructed at run time. In this case, you should also consider using the query builder methods of instead of constructing an Entity SQL query string at run time. -- When you want to define a query as part of the model definition. Only Entity SQL is supported in a data model. For more information, see [QueryView Element (MSL)](/ef/ef6/modeling/designer/advanced/edmx/msl-spec#queryview-element-msl) +- When you want to define a query as part of the model definition. Only Entity SQL is supported in a data model. For more information, see [QueryView Element (MSL)](/ef/ef6/modeling/designer/advanced/edmx/msl-spec#queryview-element-msl). - When using EntityClient to return read-only entity data as rowsets using a . For more information, see [EntityClient Provider for the Entity Framework](../entityclient-provider-for-the-entity-framework.md). diff --git a/docs/framework/ui-automation/implementing-the-ui-automation-selectionitem-control-pattern.md b/docs/framework/ui-automation/implementing-the-ui-automation-selectionitem-control-pattern.md index bb91d1c4480c2..87ac7e832fff8 100644 --- a/docs/framework/ui-automation/implementing-the-ui-automation-selectionitem-control-pattern.md +++ b/docs/framework/ui-automation/implementing-the-ui-automation-selectionitem-control-pattern.md @@ -15,7 +15,7 @@ ms.assetid: 76b0949a-5b23-4cfc-84cc-154f713e2e12 This topic introduces guidelines and conventions for implementing , including information about properties, methods, and events. Links to additional references are listed at the end of the overview. - The control pattern is used to support controls that act as individual, selectable child items of container controls that implement . For examples of controls that implement the SelectionItem control pattern, see [Control Pattern Mapping for UI Automation Clients](control-pattern-mapping-for-ui-automation-clients.md) + The control pattern is used to support controls that act as individual, selectable child items of container controls that implement . For examples of controls that implement the SelectionItem control pattern, see [Control Pattern Mapping for UI Automation Clients](control-pattern-mapping-for-ui-automation-clients.md). diff --git a/docs/framework/ui-automation/using-ui-automation-for-automated-testing.md b/docs/framework/ui-automation/using-ui-automation-for-automated-testing.md index 5ec9c098ddd1b..f6e4abd691132 100644 --- a/docs/framework/ui-automation/using-ui-automation-for-automated-testing.md +++ b/docs/framework/ui-automation/using-ui-automation-for-automated-testing.md @@ -57,7 +57,7 @@ ms.assetid: 3a0435c0-a791-4ad7-ba92-a4c1d1231fde Programmatic access provides the ability to imitate, through code, any interaction and experience exposed by traditional mouse and keyboard input. UI Automation enables programmatic access through five components: -- The UI Automation tree facilitates navigation through the structure of the UI. The tree is built from the collection of hWnd's. For more information, see [UI Automation Tree Overview](ui-automation-tree-overview.md) +- The UI Automation tree facilitates navigation through the structure of the UI. The tree is built from the collection of hWnd's. For more information, see [UI Automation Tree Overview](ui-automation-tree-overview.md). - Automation elements are individual components in the UI. These can often be more granular than an hWnd. For more information, see [UI Automation Control Types Overview](ui-automation-control-types-overview.md). diff --git a/docs/framework/unmanaged-api/debugging/cordebugstatechange-enumeration.md b/docs/framework/unmanaged-api/debugging/cordebugstatechange-enumeration.md index f1f02fb394977..6fe5b87e12a67 100644 --- a/docs/framework/unmanaged-api/debugging/cordebugstatechange-enumeration.md +++ b/docs/framework/unmanaged-api/debugging/cordebugstatechange-enumeration.md @@ -35,7 +35,7 @@ typedef enum CorDebugStateChange ## Remarks - A member of the `CorDebugStateChange` enumeration is provided as an argument when the debugger calls the `ProcessStateChanged` method either with [ICorDebugProcess4::ProcessStateChanged](icordebugprocess4-processstatechanged-method.md) or [ICorDebugProcess6::ProcessStateChanged](icordebugprocess6-processstatechanged-method.md) + A member of the `CorDebugStateChange` enumeration is provided as an argument when the debugger calls the `ProcessStateChanged` method either with [ICorDebugProcess4::ProcessStateChanged](icordebugprocess4-processstatechanged-method.md) or [ICorDebugProcess6::ProcessStateChanged](icordebugprocess6-processstatechanged-method.md). ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/debugging-enumerations.md b/docs/framework/unmanaged-api/debugging/debugging-enumerations.md index b763f3688835e..edbad3f929b77 100644 --- a/docs/framework/unmanaged-api/debugging/debugging-enumerations.md +++ b/docs/framework/unmanaged-api/debugging/debugging-enumerations.md @@ -17,7 +17,7 @@ This section describes the unmanaged enumerations that the debugging API uses. Provides values that are used by the [ICLRDebugging::OpenVirtualProcess](iclrdebugging-openvirtualprocess-method.md) method. [CLRDataAddressType Enumeration](clrdataaddresstype-enumeration.md)\ - Indicates the type of data contained at a given address by the [IXCLRDataProcess::GetAddressType](ixclrdataprocess-getaddresstype-method.md) + Indicates the type of data contained at a given address by the [IXCLRDataProcess::GetAddressType](ixclrdataprocess-getaddresstype-method.md). [CLRDataByNameFlag Enumeration](clrdatabynameflag-enumeration.md)\ Indicates how names should match in a search. diff --git a/docs/framework/wcf/diagnostics/security-concerns-for-message-logging.md b/docs/framework/wcf/diagnostics/security-concerns-for-message-logging.md index 130fd8eb8fb2b..a105b7835761f 100644 --- a/docs/framework/wcf/diagnostics/security-concerns-for-message-logging.md +++ b/docs/framework/wcf/diagnostics/security-concerns-for-message-logging.md @@ -6,108 +6,108 @@ ms.assetid: 21f513f2-815b-47f3-85a6-03c008510038 --- # Security Concerns for Message Logging -This topic describes how you can protect sensitive data from being exposed in message logs, as well as events generated by message logging. - -## Security Concerns - -### Logging Sensitive Information - - Windows Communication Foundation (WCF) does not modify any data in application-specific headers and body. WCF also does not track personal information in application-specific headers or body data. - - When message logging is enabled, personal information in application-specific headers, such as, a query string; and body information, such as, a credit card number, can become visible in the logs. The application deployer is responsible for enforcing access control on the configuration and log files. If you do not want this kind of information to be visible, you should disable logging, or filter out part of the data if you want to share the logs. - - The following tips can help you to prevent the content of a log file from being exposed unintentionally: - -- Ensure that the log files are protected by Access Control Lists (ACL) both in Web-host and self-host scenarios. - -- Choose a file extension that cannot be easily served using a Web request. For example, the .xml file extension is not a safe choice. You can check the Internet Information Services (IIS) administration guide to see a list of extensions that can be served. - -- Specify an absolute path for the log file location, which should be outside of the Web host vroot public directory to prevent it from being accessed by an external party using a Web browser. - - By default, keys and personally identifiable information (PII) such as username and password are not logged in traces and logged messages. A machine administrator, however, can use the `enableLoggingKnownPII` attribute in the `machineSettings` element of the Machine.config file to permit applications running on the machine to log known personally identifiable information (PII). The following configuration demonstrates how to do this: - -```xml - - - - +This topic describes how you can protect sensitive data from being exposed in message logs, as well as events generated by message logging. + +## Security Concerns + +### Logging Sensitive Information + + Windows Communication Foundation (WCF) does not modify any data in application-specific headers and body. WCF also does not track personal information in application-specific headers or body data. + + When message logging is enabled, personal information in application-specific headers, such as a query string; and body information, such as a credit card number, can become visible in the logs. The application deployer is responsible for enforcing access control on the configuration and log files. If you do not want this kind of information to be visible, you should disable logging, or filter out part of the data if you want to share the logs. + + The following tips can help you to prevent the content of a log file from being exposed unintentionally: + +- Ensure that the log files are protected by Access Control Lists (ACL) both in Web-host and self-host scenarios. + +- Choose a file extension that cannot be easily served using a Web request. For example, the .xml file extension is not a safe choice. You can check the Internet Information Services (IIS) administration guide to see a list of extensions that can be served. + +- Specify an absolute path for the log file location, which should be outside of the Web host vroot public directory to prevent it from being accessed by an external party using a Web browser. + + By default, keys and personally identifiable information (PII) such as username and password are not logged in traces and logged messages. A machine administrator, however, can use the `enableLoggingKnownPII` attribute in the `machineSettings` element of the Machine.config file to permit applications running on the machine to log known personally identifiable information (PII). The following configuration demonstrates how to do this: + +```xml + + + + -``` - - An application deployer can then use the `logKnownPii` attribute in either the App.config or Web.config file to enable PII logging as follows: - -```xml - - - - - - - - - -``` - - Only when both settings are `true` is PII logging enabled. The combination of two switches allows the flexibility to log known PII for each application. - +``` + + An application deployer can then use the `logKnownPii` attribute in either the App.config or Web.config file to enable PII logging as follows: + +```xml + + + + + + + + + +``` + + Only when both settings are `true` is PII logging enabled. The combination of two switches allows the flexibility to log known PII for each application. + > [!IMPORTANT] -> In [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] the `logEntireMessage` and `logKnownPii` flags must also be set to `true` in the Web.config file or the App.config file to enable PII logging, as show in the following example ` - - - - - - +> In [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] the `logEntireMessage` and `logKnownPii` flags must also be set to `true` in the Web.config file or the App.config file to enable PII logging, as show in the following example ` + + + + + + - - - - - - -``` - - If the `` element exists outside the Machine.config file, the system throws a . - - The changes are effective only when the application starts or restarts. An event is logged at startup when both attributes are set to `true`. An event is also logged if `logKnownPii` is set to `true` but `enableLoggingKnownPii` is `false`. - - The machine administrator and application deployer should exercise extreme caution when using these two switches. If PII logging is enabled, security keys and PII are logged. If it is disabled, sensitive and application-specific data is still logged in message headers and bodies. For a more thorough discussion about privacy and protecting PII from being exposed, see [User Privacy](/previous-versions/dotnet/articles/aa480490(v=msdn.10)). - + logKnownPii="true"> + + + + + + +``` + + If the `` element exists outside the Machine.config file, the system throws a . + + The changes are effective only when the application starts or restarts. An event is logged at startup when both attributes are set to `true`. An event is also logged if `logKnownPii` is set to `true` but `enableLoggingKnownPii` is `false`. + + The machine administrator and application deployer should exercise extreme caution when using these two switches. If PII logging is enabled, security keys and PII are logged. If it is disabled, sensitive and application-specific data is still logged in message headers and bodies. For a more thorough discussion about privacy and protecting PII from being exposed, see [User Privacy](/previous-versions/dotnet/articles/aa480490(v=msdn.10)). + > [!CAUTION] -> PII is not hidden in malformed messages. Such messaged are logged as-is without any modification. Attributes mentioned previously have no effect on this. - -### Custom Trace Listener - - Adding a custom trace listener on the Message Logging trace source is a privilege that should be restricted to the administrator. This is because malicious custom listeners can be configured to send messages remotely, which leads to sensitive information disclosure. In addition, if you configure a custom listener to send messages on the wire, such as, to a remote database, you should enforce proper access control on the message logs in the remote machine. - -## Events Triggered by Message Logging - - The following lists all the events emitted by message logging. - -- Message logging on: This event is emitted when message logging is enabled in configuration, or through WMI. The content of the event is "Message logging has been turned on. Sensitive information may be logged in clear text, even if they were encrypted on the wire, for example, message bodies." - -- Message logging off: This event is emitted when message logging is disabled through WMI. The content of the event is "Message logging has been turned off." - -- Log Known PII On: This event is emitted when logging of known PII is enabled. This happens when the `enableLoggingKnownPii` attribute in the `machineSettings` element of the Machine.config file is set to `true`, and the `logKnownPii` attribute of the `source` element in either the App.config or Web.config file is set to `true`. - -- Log Known PII Not Allowed: This event is emitted when logging of known PII is not allowed. This happens when the `logKnownPii` attribute of the `source` element in either the App.config or Web.config file is set to `true`, but the `enableLoggingKnownPii` attribute in the `machineSettings` element of the Machine.config file is set to `false`. No exception is thrown. - - These events can be viewed in the Event Viewer tool that comes with Windows. For more information on this, see [Event Logging](./event-logging/index.md). - +> PII is not hidden in malformed messages. Such messaged are logged as-is without any modification. Attributes mentioned previously have no effect on this. + +### Custom Trace Listener + + Adding a custom trace listener on the Message Logging trace source is a privilege that should be restricted to the administrator. This is because malicious custom listeners can be configured to send messages remotely, which leads to sensitive information disclosure. In addition, if you configure a custom listener to send messages on the wire, such as to a remote database, you should enforce proper access control on the message logs in the remote machine. + +## Events Triggered by Message Logging + + The following lists all the events emitted by message logging. + +- Message logging on: This event is emitted when message logging is enabled in configuration, or through WMI. The content of the event is "Message logging has been turned on. Sensitive information may be logged in clear text, even if they were encrypted on the wire, for example, message bodies." + +- Message logging off: This event is emitted when message logging is disabled through WMI. The content of the event is "Message logging has been turned off." + +- Log Known PII On: This event is emitted when logging of known PII is enabled. This happens when the `enableLoggingKnownPii` attribute in the `machineSettings` element of the Machine.config file is set to `true`, and the `logKnownPii` attribute of the `source` element in either the App.config or Web.config file is set to `true`. + +- Log Known PII Not Allowed: This event is emitted when logging of known PII is not allowed. This happens when the `logKnownPii` attribute of the `source` element in either the App.config or Web.config file is set to `true`, but the `enableLoggingKnownPii` attribute in the `machineSettings` element of the Machine.config file is set to `false`. No exception is thrown. + + These events can be viewed in the Event Viewer tool that comes with Windows. For more information on this, see [Event Logging](./event-logging/index.md). + ## See also - [Message Logging](message-logging.md) diff --git a/docs/framework/wcf/diagnostics/tracing/security-concerns-and-useful-tips-for-tracing.md b/docs/framework/wcf/diagnostics/tracing/security-concerns-and-useful-tips-for-tracing.md index 0d423b97a2a4a..96e21d0a35792 100644 --- a/docs/framework/wcf/diagnostics/tracing/security-concerns-and-useful-tips-for-tracing.md +++ b/docs/framework/wcf/diagnostics/tracing/security-concerns-and-useful-tips-for-tracing.md @@ -6,88 +6,88 @@ ms.assetid: 88bc2880-ecb9-47cd-9816-39016a07076f --- # Security Concerns and Useful Tips for Tracing -This topic describes how you can protect sensitive information from being exposed, as well as useful tips when using WebHost. - -## Using a Custom Trace Listener with WebHost - - If you are writing your own trace listener, you should be aware of the possibility that traces might be lost in the case of a Web-hosted service. When WebHost recycles, it shuts down the live process while a duplicate takes over. However, the two processes must still have access to the same resource for some time, which is dependent on the listener type. In this case, , `XmlWriterTraceListener` creates a new trace file for the second process; while Windows event tracing manages multiple processes within the same session and gives access to the same file. If your own listener does not provide similar functionalities, traces can be lost when the file is locked up by the two processes. - - You should also be aware that a custom trace listener can send traces and messages on the wire, for example, to a remote database. As an application deployer, you should configure custom listeners with appropriate access control. You should also apply security control on any personal information that can be exposed at the remote location. - -## Logging Sensitive Information - - Traces contain message headers when a message is in scope. When tracing is enabled, personal information in application-specific headers, such as, a query string; and body information, such as, a credit card number, can become visible in the logs. The application deployer is responsible for enforcing access control on the configuration and trace files. If you do not want this kind of information to be visible, you should disable tracing, or filter out part of the data if you want to share the trace logs. - - The following tips can help you to prevent the content of a trace file from being exposed unintentionally: - -- Ensure that the log files are protected by Access Control Lists (ACL) both in WebHost and self-host scenarios. - -- Choose a file extension that cannot be easily served using a Web request. For example, the .xml file extension is not a safe choice. You can check the IIS administration guide to see a list of extensions that can be served. - -- Specify an absolute path for the log file location, which should be outside of the WebHost vroot public directory to prevent it from being accessed by an external party using a Web browser. - - By default, keys and personally identifiable information (PII) such as username and password are not logged in traces and logged messages. A machine administrator, however, can use the `enableLoggingKnownPII` attribute in the `machineSettings` element of the Machine.config file to permit applications running on the machine to log known personally identifiable information (PII) as follows: - -```xml - - - - +This topic describes how you can protect sensitive information from being exposed, as well as useful tips when using WebHost. + +## Using a Custom Trace Listener with WebHost + + If you are writing your own trace listener, you should be aware of the possibility that traces might be lost in the case of a Web-hosted service. When WebHost recycles, it shuts down the live process while a duplicate takes over. However, the two processes must still have access to the same resource for some time, which is dependent on the listener type. In this case, , `XmlWriterTraceListener` creates a new trace file for the second process; while Windows event tracing manages multiple processes within the same session and gives access to the same file. If your own listener does not provide similar functionalities, traces can be lost when the file is locked up by the two processes. + + You should also be aware that a custom trace listener can send traces and messages on the wire, for example, to a remote database. As an application deployer, you should configure custom listeners with appropriate access control. You should also apply security control on any personal information that can be exposed at the remote location. + +## Logging Sensitive Information + + Traces contain message headers when a message is in scope. When tracing is enabled, personal information in application-specific headers, such as a query string; and body information, such as a credit card number, can become visible in the logs. The application deployer is responsible for enforcing access control on the configuration and trace files. If you do not want this kind of information to be visible, you should disable tracing, or filter out part of the data if you want to share the trace logs. + + The following tips can help you to prevent the content of a trace file from being exposed unintentionally: + +- Ensure that the log files are protected by Access Control Lists (ACL) both in WebHost and self-host scenarios. + +- Choose a file extension that cannot be easily served using a Web request. For example, the .xml file extension is not a safe choice. You can check the IIS administration guide to see a list of extensions that can be served. + +- Specify an absolute path for the log file location, which should be outside of the WebHost vroot public directory to prevent it from being accessed by an external party using a Web browser. + + By default, keys and personally identifiable information (PII) such as username and password are not logged in traces and logged messages. A machine administrator, however, can use the `enableLoggingKnownPII` attribute in the `machineSettings` element of the Machine.config file to permit applications running on the machine to log known personally identifiable information (PII) as follows: + +```xml + + + + -``` - - An application deployer can then use the `logKnownPii` attribute in either the App.config or Web.config file to enable PII logging as follows: - -```xml - - - - - - - - - -``` - - Only when both settings are `true` is PII logging enabled. The combination of two switches allows the flexibility to log known PII for each application. - - You should be aware that if you specify two or more custom sources in a configuration file, only the attributes of the first source are read. The others are ignored. This means that, for the following App.config, file, PII is not logged for both sources even though PII logging is explicitly enabled for the second source. - -```xml - - - - - - - +``` + + An application deployer can then use the `logKnownPii` attribute in either the App.config or Web.config file to enable PII logging as follows: + +```xml + + + + + + + + + +``` + + Only when both settings are `true` is PII logging enabled. The combination of two switches allows the flexibility to log known PII for each application. + + You should be aware that if you specify two or more custom sources in a configuration file, only the attributes of the first source are read. The others are ignored. This means that, for the following App.config, file, PII is not logged for both sources even though PII logging is explicitly enabled for the second source. + +```xml + + + + + + + - - - - - - -``` - - If the `` element exists outside the Machine.config file, the system throws a . - - The changes are effective only when the application starts or restarts. An event is logged at startup when both attributes are set to `true`. An event is also logged if `logKnownPii` is set to `true` but `enableLoggingKnownPii` is `false`. - - For more information on PII logging, see [PII Security Lockdown](../../samples/pii-security-lockdown.md) sample. - - The machine administrator and application deployer should exercise extreme caution when using these two switches. If PII logging is enabled, security keys and PII are logged. If it is disabled, sensitive and application-specific data is still logged in message headers and bodies. For a more thorough discussion on privacy and protecting PII from being exposed, see [User Privacy](/previous-versions/dotnet/articles/aa480490(v=msdn.10)). - - In addition, the IP address of the message sender is logged once per connection for connection-oriented transports, and once per message sent otherwise. This is done without the consent of the sender. However, this logging only occurs at the Information or Verbose tracing levels, which are not the default or recommended tracing levels in production, except for live debugging. - + logKnownPii="true"> + + + + + + +``` + + If the `` element exists outside the Machine.config file, the system throws a . + + The changes are effective only when the application starts or restarts. An event is logged at startup when both attributes are set to `true`. An event is also logged if `logKnownPii` is set to `true` but `enableLoggingKnownPii` is `false`. + + For more information on PII logging, see [PII Security Lockdown](../../samples/pii-security-lockdown.md) sample. + + The machine administrator and application deployer should exercise extreme caution when using these two switches. If PII logging is enabled, security keys and PII are logged. If it is disabled, sensitive and application-specific data is still logged in message headers and bodies. For a more thorough discussion on privacy and protecting PII from being exposed, see [User Privacy](/previous-versions/dotnet/articles/aa480490(v=msdn.10)). + + In addition, the IP address of the message sender is logged once per connection for connection-oriented transports, and once per message sent otherwise. This is done without the consent of the sender. However, this logging only occurs at the Information or Verbose tracing levels, which are not the default or recommended tracing levels in production, except for live debugging. + ## See also - [Tracing](index.md) diff --git a/docs/framework/wcf/feature-details/hosting-in-windows-process-activation-service.md b/docs/framework/wcf/feature-details/hosting-in-windows-process-activation-service.md index 09c80694f0b77..cd014740b920b 100644 --- a/docs/framework/wcf/feature-details/hosting-in-windows-process-activation-service.md +++ b/docs/framework/wcf/feature-details/hosting-in-windows-process-activation-service.md @@ -2,50 +2,50 @@ title: "Hosting in Windows Process Activation Service" description: Learn about how WAS manages the activation and lifetime of the worker processes containing applications that host WCF services. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "hosting services [WCF], WAS" ms.assetid: d2b9d226-15b7-41fc-8c9a-cb651ac20ecd --- # Hosting in Windows Process Activation Service -The Windows Process Activation Service (WAS) manages the activation and lifetime of the worker processes that contain applications that host Windows Communication Foundation (WCF) services. The WAS process model generalizes the IIS 6.0 process model for the HTTP server by removing the dependency on HTTP. This allows WCF services to use both HTTP and non-HTTP protocols, such as Net.TCP, in a hosting environment that supports message-based activation and offers the ability to host a large number of applications on a given machine. - - For more information about building a WCF service that runs in the WAS hosting environment, see [How to: Host a WCF Service in WAS](how-to-host-a-wcf-service-in-was.md). - - The WAS process model provides several features that enable applications to be hosted in a way that is more robust, more manageable, and that uses resources efficiently: - -- Message-based activation of applications and worker process applications start and stop dynamically in response to incoming work items that arrive using HTTP and non-HTTP network protocols. - -- Robust application and worker process recycling to maintain the health of running applications. - -- Centralized application configuration and management. - -- Allows applications to take advantage of the IIS process model without requiring the deployment footprint of a full IIS installation. -[Windows Server AppFabric](/previous-versions/appfabric/ff384253(v=azure.10)) works with IIS 7.0 and Windows Process Activation Service (WAS) to provide a rich application hosting environment for NET4 WCF and WF services. These benefits include process life-cycle management, process recycling, shared hosting, rapid failure protection, process orphaning, on-demand activation, and health monitoring. For detailed information, see [AppFabric Hosting Features](/previous-versions/appfabric/ee677189(v=azure.10)) and [AppFabric Hosting Concepts](/previous-versions/appfabric/ee677371(v=azure.10)). - -## Elements of the WAS Addressing Model - - Applications have Uniform Resource Identifier (URI) addresses, which are the code units whose lifetime and execution environment are managed by the server. A single WAS server instance can be home to many different applications. Servers organize applications into groups called *sites*. Within a site, applications are arranged in a hierarchical manner that reflects the structure of the URIs that serve as their external addresses. - - Application addresses have two parts: a base URI prefix and an application-specific, relative address (path), which provide the external address for an application when joined together. The base URI prefix is constructed from the site binding and is used for all the applications under the site. Application addresses are then constructed by taking application-specific path fragments (such as, "/applicationOne") and appending them to the base URI prefix (for example, "net.tcp://localhost") to arrive at the full application URI. - - The following table illustrates several possible addressing scenarios for WAS sites with both HTTP and non-HTTP site bindings. - -|Scenario|Site bindings|Application path|Base application URIs| -|--------------|-------------------|----------------------|---------------------------| -|HTTP Only|http: *:80:\*|/appTwo|`http://localhost/appTwo/`| -|Both HTTP and Non-HTTP|http: *:80:\*

net.tcp: 808:\*|/appTwo|`http://localhost/appTwo/`
`net.tcp://localhost/appTwo/`| -|Non-HTTP only|net.pipe: *|/appThree|`net.pipe://appThree/`| - - Services and resources within an application can also be addressed. Within an application, application resources are addressed relative to the base application path. For example, assume that a site on a machine name contoso.com has site bindings for both the HTTP and Net.TCP protocols. Also assume that the site contains one application located at /Billing, which exposes a service at GetOrders.svc. Then, if the GetOrders.svc service exposed an endpoint with a relative address of SecureEndpoint, the service endpoint would be exposed at the following two URIs: - +The Windows Process Activation Service (WAS) manages the activation and lifetime of the worker processes that contain applications that host Windows Communication Foundation (WCF) services. The WAS process model generalizes the IIS 6.0 process model for the HTTP server by removing the dependency on HTTP. This allows WCF services to use both HTTP and non-HTTP protocols, such as Net.TCP, in a hosting environment that supports message-based activation and offers the ability to host a large number of applications on a given machine. + + For more information about building a WCF service that runs in the WAS hosting environment, see [How to: Host a WCF Service in WAS](how-to-host-a-wcf-service-in-was.md). + + The WAS process model provides several features that enable applications to be hosted in a way that is more robust, more manageable, and that uses resources efficiently: + +- Message-based activation of applications and worker process applications start and stop dynamically in response to incoming work items that arrive using HTTP and non-HTTP network protocols. + +- Robust application and worker process recycling to maintain the health of running applications. + +- Centralized application configuration and management. + +- Allows applications to take advantage of the IIS process model without requiring the deployment footprint of a full IIS installation. +[Windows Server AppFabric](/previous-versions/appfabric/ff384253(v=azure.10)) works with IIS 7.0 and Windows Process Activation Service (WAS) to provide a rich application hosting environment for NET4 WCF and WF services. These benefits include process life-cycle management, process recycling, shared hosting, rapid failure protection, process orphaning, on-demand activation, and health monitoring. For detailed information, see [AppFabric Hosting Features](/previous-versions/appfabric/ee677189(v=azure.10)) and [AppFabric Hosting Concepts](/previous-versions/appfabric/ee677371(v=azure.10)). + +## Elements of the WAS Addressing Model + + Applications have Uniform Resource Identifier (URI) addresses, which are the code units whose lifetime and execution environment are managed by the server. A single WAS server instance can be home to many different applications. Servers organize applications into groups called *sites*. Within a site, applications are arranged in a hierarchical manner that reflects the structure of the URIs that serve as their external addresses. + + Application addresses have two parts: a base URI prefix and an application-specific, relative address (path), which provide the external address for an application when joined together. The base URI prefix is constructed from the site binding and is used for all the applications under the site. Application addresses are then constructed by taking application-specific path fragments (for example, "/applicationOne") and appending them to the base URI prefix (for example, "net.tcp://localhost") to arrive at the full application URI. + + The following table illustrates several possible addressing scenarios for WAS sites with both HTTP and non-HTTP site bindings. + +| Scenario | Site bindings | Application path | Base application URIs | +|---------------|---------------|------------------|----------------------------| +| HTTP Only | http: *:80:\* | /appTwo | `http://localhost/appTwo/` | +| Both HTTP and Non-HTTP | http: *:80:\*

net.tcp: 808:\* | /appTwo|`http://localhost/appTwo/`
`net.tcp://localhost/appTwo/` | +| Non-HTTP only | net.pipe: * | /appThree | `net.pipe://appThree/` | + + Services and resources within an application can also be addressed. Within an application, application resources are addressed relative to the base application path. For example, assume that a site on a machine name contoso.com has site bindings for both the HTTP and Net.TCP protocols. Also assume that the site contains one application located at /Billing, which exposes a service at GetOrders.svc. Then, if the GetOrders.svc service exposed an endpoint with a relative address of SecureEndpoint, the service endpoint would be exposed at the following two URIs: + - `http://contoso.com/Billing/GetOrders.svc/SecureEndpoint` - `net.tcp://contoso.com/Billing/GetOrders.svc/SecureEndpoint` - -## The WAS Runtime - Applications are organized into sites for the purposes of addressing and management. At run time, applications are also grouped together into application pools. An application pool can house many different applications from many different sites. All of the applications inside an application pool share a common set of run-time characteristics. For example, they all run under the same version of the common language runtime (CLR) and they all share a common process identity. Each application pool corresponds to an instance of a worker process (w3wp.exe). Each managed application running inside of a shared application pool is isolated from other applications by means of a CLR AppDomain. - +## The WAS Runtime + + Applications are organized into sites for the purposes of addressing and management. At run time, applications are also grouped together into application pools. An application pool can house many different applications from many different sites. All of the applications inside an application pool share a common set of run-time characteristics. For example, they all run under the same version of the common language runtime (CLR) and they all share a common process identity. Each application pool corresponds to an instance of a worker process (w3wp.exe). Each managed application running inside of a shared application pool is isolated from other applications by means of a CLR AppDomain. + ## See also - [WAS Activation Architecture](was-activation-architecture.md) diff --git a/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md b/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md index 8531775a0ce0a..4aca3c304a24d 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md +++ b/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md @@ -25,7 +25,7 @@ Workflows go idle when they encounter a bookmark that must be resumed by some ex ``` - The `timeToUnload` attribute specifies the time period between when a workflow service instance goes idle and when the workflow service is unloaded. The `timeToPersist` attribute specifies the time period between when a workflow service instance goes idle and when the workflow service instance is persisted. The default value for `timeToUnload` is 1 minute. The default value for `timeToPersist` is . If you want to keep idle instances in memory but persist them for robustness, set values so that `timeToPersist` < `timeToUnload`. If you want to prevent idle instances from being unloaded, set `timeToUnload` to . For more information about , see [Workflow Service Host Extensibility](workflow-service-host-extensibility.md) + The `timeToUnload` attribute specifies the time period between when a workflow service instance goes idle and when the workflow service is unloaded. The `timeToPersist` attribute specifies the time period between when a workflow service instance goes idle and when the workflow service instance is persisted. The default value for `timeToUnload` is 1 minute. The default value for `timeToPersist` is . If you want to keep idle instances in memory but persist them for robustness, set values so that `timeToPersist` < `timeToUnload`. If you want to prevent idle instances from being unloaded, set `timeToUnload` to . For more information about , see [Workflow Service Host Extensibility](workflow-service-host-extensibility.md). > [!NOTE] > The preceding configuration sample is using simplified configuration. For more information, see [Simplified Configuration](../simplified-configuration.md). diff --git a/docs/framework/wcf/feature-details/how-to-configure-persistence-with-workflowservicehost.md b/docs/framework/wcf/feature-details/how-to-configure-persistence-with-workflowservicehost.md index f2dfc54fa0942..aeabd07faf2e0 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-persistence-with-workflowservicehost.md +++ b/docs/framework/wcf/feature-details/how-to-configure-persistence-with-workflowservicehost.md @@ -29,7 +29,7 @@ This article describes how to configure the SQL Workflow Instance Store feature For more information about how to configure the SQL workflow instance store, see [How to: Enable SQL Persistence for Workflows and Workflow Services](../../windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md). For more information about the individual settings for the `` behavior element, see [SQL Workflow Instance Store](../../windows-workflow-foundation/sql-workflow-instance-store.md). > [!NOTE] - > The preceding configuration example uses simplified configuration. For more information, see [Simplified Configuration](../simplified-configuration.md) + > The preceding configuration example uses simplified configuration. For more information, see [Simplified Configuration](../simplified-configuration.md). ## To Configure the SQL Workflow Instance Store in Code @@ -50,7 +50,7 @@ This article describes how to configure the SQL Workflow Instance Store feature For more information about how to configure the SQL workflow instance store, see [How to: Enable SQL Persistence for Workflows and Workflow Services](../../windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md). For more information about the individual settings for the behavior element, see [SQL Workflow Instance Store](../../windows-workflow-foundation/sql-workflow-instance-store.md). > [!NOTE] - > The preceding configuration example uses simplified configuration. For more information, see [Simplified Configuration](../simplified-configuration.md) + > The preceding configuration example uses simplified configuration. For more information, see [Simplified Configuration](../simplified-configuration.md). For an example of how to configure persistence programmatically see [How to: Enable Persistence for Workflows and Workflow Services](../../windows-workflow-foundation/how-to-enable-persistence-for-workflows-and-workflow-services.md). diff --git a/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-iis.md b/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-iis.md index 157d62c036e2c..b8f221f04b95f 100644 --- a/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-iis.md +++ b/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-iis.md @@ -17,7 +17,7 @@ This topic outlines the basic steps required to create a Windows Communication F ### To create a service hosted by IIS -1. Confirm that IIS is installed and running on your computer. For more information about installing and configuring IIS see [Installing and Configuring IIS 7.0](/iis/install/installing-iis-7/installing-necessary-iis-components-on-windows-vista) +1. Confirm that IIS is installed and running on your computer. For more information about installing and configuring IIS see [Installing and Configuring IIS 7.0](/iis/install/installing-iis-7/installing-necessary-iis-components-on-windows-vista). 2. Create a new folder for your application files called "IISHostedCalcService", ensure that ASP.NET has access to the contents of the folder, and use the IIS management tool to create a new IIS application that is physically located in this application directory. When creating an alias for the application directory use "IISHostedCalc". diff --git a/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md b/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md index 596f47d64dbfa..4a247e5800117 100644 --- a/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md +++ b/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md @@ -19,10 +19,10 @@ The Windows Communication Foundation (WCF) WEB HTTP programming model provides t There are no extra restrictions on the types of data that can be returned from a WEB HTTP service. Any serializable type can be returned from an WEB HTTP service operation. Because WEB HTTP service operations can be invoke by a web browser there is a limitation on what data types can be specified in a URL. For more information on what types are supported by default see the **UriTemplate Query String Parameters and URLs** section below. The default behavior can be changed by providing your own T:System.ServiceModel.Dispatcher.QueryStringConverter implementation which specifies how to convert the parameters specified in a URL to the actual parameter type. For more information, see > [!CAUTION] -> Services written with the WCF WEB HTTP programming model do not use SOAP messages. Because SOAP is not used, the security features provided by WCF cannot be used. You can, however use transport-based security by hosting your service with HTTPS. For more information about WCF security, see [Security Overview](security-overview.md) +> Services written with the WCF WEB HTTP programming model do not use SOAP messages. Because SOAP is not used, the security features provided by WCF cannot be used. You can, however use transport-based security by hosting your service with HTTPS. For more information about WCF security, see [Security Overview](security-overview.md). > [!WARNING] -> Installing the WebDAV extension for IIS can cause Web HTTP services to return an HTTP 405 error as the WebDAV extension attempts to handle all PUT requests. To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. For more information, see [IIS and WebDav](/iis/publish/using-webdav/webdav-extension-video-walkthrough) +> Installing the WebDAV extension for IIS can cause Web HTTP services to return an HTTP 405 error as the WebDAV extension attempts to handle all PUT requests. To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. For more information, see [IIS and WebDav](/iis/publish/using-webdav/webdav-extension-video-walkthrough). ## URI Processing with UriTemplate and UriTemplateTable @@ -50,7 +50,7 @@ The Windows Communication Foundation (WCF) WEB HTTP programming model provides t There are many times (especially on the server, where dispatching a request to a service operation based on the URI is necessary) that you want to keep track of a set of objects in a data structure that can independently address each of the contained templates. represents a set of URI templates and selects the best match given a set of templates and a candidate URI. This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary. - The WCF Service Model makes use of and to associate service operations with a set of URIs described by a . A service operation is associated with a , using either the or the . For more information about and , see [UriTemplate and UriTemplateTable](uritemplate-and-uritemplatetable.md) + The WCF Service Model makes use of and to associate service operations with a set of URIs described by a . A service operation is associated with a , using either the or the . For more information about and , see [UriTemplate and UriTemplateTable](uritemplate-and-uritemplatetable.md). ## WebGet and WebInvoke Attributes @@ -94,7 +94,7 @@ interface ICustomer } ``` - To see a complete sample of a WCF service that uses the WCF WEB HTTP programming model, see [How to: Create a Basic WCF Web HTTP Service](how-to-create-a-basic-wcf-web-http-service.md) +For a complete sample of a WCF service that uses the WCF WEB HTTP programming model, see [How to: Create a Basic WCF Web HTTP Service](how-to-create-a-basic-wcf-web-http-service.md). ## UriTemplate Query String Parameters and URLs @@ -128,9 +128,7 @@ interface ICustomer The WCF WEB HTTP programming model has new features to work with many different data formats. At the binding layer, the can read and write the following different kinds of data: - XML - - JSON - - Opaque binary streams This means the WCF WEB HTTP programming model can handle any type of data but, you may be programming against . diff --git a/docs/framework/wcf/samples/message-security-certificate.md b/docs/framework/wcf/samples/message-security-certificate.md index f70daa123b750..c8868faa2ca6c 100644 --- a/docs/framework/wcf/samples/message-security-certificate.md +++ b/docs/framework/wcf/samples/message-security-certificate.md @@ -236,7 +236,7 @@ The Setup.bat batch file included with the Message Security samples enables you makecert.exe -sr LocalMachine -ss MY -a sha1 -n CN=%SERVER_NAME% -sky exchange -pe ``` - The %SERVER_NAME% variable specifies the server name. The certificate is stored in the LocalMachine store. If the Setup.bat batch file is run with an argument of service (such as, **setup.bat service**) the %SERVER_NAME% contains the fully-qualified domain name of the computer. Otherwise it defaults to localhost. + The %SERVER_NAME% variable specifies the server name. The certificate is stored in the LocalMachine store. If the Setup.bat batch file is run with an argument of service (such as **setup.bat service**) the %SERVER_NAME% contains the fully-qualified domain name of the computer. Otherwise it defaults to localhost. - Installing the server certificate into the client's trusted certificate store. diff --git a/docs/framework/wcf/samples/message-security-over-message-queuing.md b/docs/framework/wcf/samples/message-security-over-message-queuing.md index 259e39e825556..7560333720351 100644 --- a/docs/framework/wcf/samples/message-security-over-message-queuing.md +++ b/docs/framework/wcf/samples/message-security-over-message-queuing.md @@ -10,7 +10,7 @@ The [MessageSecurity sample](https://github.com/dotnet/samples/tree/main/framewo This sample is based on the [Transacted MSMQ Binding](transacted-msmq-binding.md) sample. The messages are encrypted and signed. -### To set up, build, and run the sample +## To set up, build, and run the sample 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). @@ -26,9 +26,9 @@ This sample is based on the [Transacted MSMQ Binding](transacted-msmq-binding.md 5. Enter `ServiceModelSamplesTransacted` as the name of the new queue. -3. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in [Building the Windows Communication Foundation Samples](building-the-samples.md). +3. To build the C# or Visual Basic edition of the solution, follow the instructions in [Building the Windows Communication Foundation Samples](building-the-samples.md). -### To run the sample on the same computer +## To run the sample on the same computer 1. Ensure that the path includes the folder that contains Makecert.exe and FindPrivateKey.exe. @@ -43,7 +43,7 @@ This sample is based on the [Transacted MSMQ Binding](transacted-msmq-binding.md 5. If the client and service are not able to communicate, see [Troubleshooting Tips for WCF Samples](/previous-versions/dotnet/netframework-3.5/ms751511(v=vs.90)). -### To run the sample across computers +## To run the sample across computers 1. Copy the Setup.bat, Cleanup.bat, and ImportClientCert.bat files to the service computer. @@ -71,7 +71,7 @@ This sample is based on the [Transacted MSMQ Binding](transacted-msmq-binding.md 13. On the client computer, launch Client.exe from the command prompt. If the client and service are not able to communicate, see [Troubleshooting Tips for WCF Samples](/previous-versions/dotnet/netframework-3.5/ms751511(v=vs.90)). -### To clean up after the sample +## To clean up after the sample - Run Cleanup.bat in the samples folder once you have finished running the sample. @@ -322,15 +322,15 @@ Processing Purchase Order: 6536e097-da96-4773-9da3-77bab4345b5d makecert.exe -sr LocalMachine -ss MY -a sha1 -n CN=%SERVER_NAME% -sky exchange -pe ``` - The %SERVER_NAME% variable specifies the server name. The certificate is stored in the LocalMachine store. If the setup batch file is run with an argument of service (such as, `setup.bat service`) the %SERVER_NAME% contains the fully-qualified domain name of the computer.Otherwise it defaults to localhost + The %SERVER_NAME% variable specifies the server name. The certificate is stored in the LocalMachine store. If the setup batch file is run with an argument of service (such as `setup.bat service`), the %SERVER_NAME% contains the fully qualified domain name of the computer. Otherwise it defaults to localhost. - Installing server certificate into the client's trusted certificate store. - The following line copies the server certificate into the client trusted people store. This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft-issued certificate—this step of populating the client certificate store with the server certificate is not required. + The following line copies the server certificate into the client trusted people store. This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft-issued certificate—this step of populating the client certificate store with the server certificate is not required. ```console certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople ``` > [!NOTE] - > If you are using a non-U.S. English edition of Microsoft Windows you must edit the Setup.bat file and replace the "NT AUTHORITY\NETWORK SERVICE" account name with your regional equivalent. + > If you're using a non-U.S. English edition of Microsoft Windows, you must edit the Setup.bat file and replace the "NT AUTHORITY\NETWORK SERVICE" account name with your regional equivalent. diff --git a/docs/framework/wcf/samples/ws-transaction-flow.md b/docs/framework/wcf/samples/ws-transaction-flow.md index a598e6a1206ac..b344848762fa0 100644 --- a/docs/framework/wcf/samples/ws-transaction-flow.md +++ b/docs/framework/wcf/samples/ws-transaction-flow.md @@ -219,9 +219,9 @@ If an exception occurred anywhere within the client's `TransactionScope` then th ### To set up, build, and run the sample -1. To build the C# or Visual Basic .NET version of the solution, follow the instructions in [Building the Windows Communication Foundation Samples](building-the-samples.md) +1. To build the C# or Visual Basic .NET version of the solution, follow the instructions in [Building the Windows Communication Foundation Samples](building-the-samples.md). -2. Ensure that you have installed SQL Server Express Edition or SQL Server, and that the connection string has been correctly set in the service's application configuration file. To run the sample without using a database, set the `usingSql` value in the service's application configuration file to `false` +2. Ensure that you have installed SQL Server Express Edition or SQL Server, and that the connection string has been correctly set in the service's application configuration file. To run the sample without using a database, set the `usingSql` value in the service's application configuration file to `false`. 3. To run the sample in a single- or cross-machine configuration, follow the instructions in [Running the Windows Communication Foundation Samples](running-the-samples.md). diff --git a/docs/framework/windows-workflow-foundation/whats-new.md b/docs/framework/windows-workflow-foundation/whats-new.md index 57b1da80921d5..715bd2c5fac0f 100644 --- a/docs/framework/windows-workflow-foundation/whats-new.md +++ b/docs/framework/windows-workflow-foundation/whats-new.md @@ -23,7 +23,7 @@ Windows Workflow Foundation (WF) in .NET Framework 4 changes several development New features of the activity library include: -- New flow control activities, such as, , , , , , and . +- New flow control activities, such as , , , , , and . - Activities for manipulating member data, such as and collection activities such as . diff --git a/docs/machine-learning/deep-learning-overview.md b/docs/machine-learning/deep-learning-overview.md index 12cf1710c4822..f26d17bca7469 100644 --- a/docs/machine-learning/deep-learning-overview.md +++ b/docs/machine-learning/deep-learning-overview.md @@ -79,7 +79,7 @@ var model = pipeline.Fit(trainingData); var predictedData = model.Transform(newData).GetColumn("PredictedLabel"); ``` -To get started training custom image classification models in ML.NET, see the [Train an image classification model in Azure using Model Builder](tutorials/image-classification-model-builder.md) +To get started training custom image classification models in ML.NET, see [Train an image classification model in Azure using Model Builder](tutorials/image-classification-model-builder.md). #### Object detection @@ -89,7 +89,7 @@ The result of the training process is an ONNX model which can then be used with At this time, there is no local support for object detection in ML.NET. -To train custom object detection models with ML.NET, see the [Detect stop signs in images with Model Builder tutorial](tutorials/object-detection-model-builder.md) +To train custom object detection models with ML.NET, see [Detect stop signs in images with Model Builder tutorial](tutorials/object-detection-model-builder.md). #### Text classification diff --git a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md index 4939667d88f40..8a833a278c0cc 100644 --- a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md +++ b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md @@ -117,7 +117,7 @@ For training, AutoML provides a sweepable pipeline with default trainers and sea - - -For the taxi fare prediction problem, since the goal is to predict a numerical value, use `Regression`. For more information on choosing a task, see [Machine learning tasks in ML.NET](../resources/tasks.md) +For the taxi fare prediction problem, since the goal is to predict a numerical value, use `Regression`. For more information on choosing a task, see [Machine learning tasks in ML.NET](../resources/tasks.md). ### Configure your experiment diff --git a/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md b/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md index 1a3feccaaa683..7d30b24637c41 100644 --- a/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md +++ b/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md @@ -17,7 +17,7 @@ Learn how to serve a pretrained ML.NET machine learning model on the web using a - [Visual Studio 2022](https://visualstudio.microsoft.com/vs/#download) with the **ASP.NET and web development workload**. - PowerShell. -- Pre-trained model. Use the [ML.NET Sentiment Analysis tutorial](../tutorials/sentiment-analysis.md) to build your own model or download this [pretrained sentiment analysis machine learning model](https://github.com/dotnet/samples/blob/main/machine-learning/models/sentimentanalysis/sentiment_model.zip) +- Pre-trained model. Use the [ML.NET Sentiment Analysis tutorial](../tutorials/sentiment-analysis.md) to build your own model or download this [pretrained sentiment analysis machine learning model](https://github.com/dotnet/samples/blob/main/machine-learning/models/sentimentanalysis/sentiment_model.zip). ## Create ASP.NET Core Web API project @@ -187,7 +187,7 @@ public class ModelOutput Once everything is set up, it's time to test the application. 1. Run the application. -1. Open PowerShell and enter the following code where PORT is the port your application is listening on. +1. Open PowerShell and enter the following code, where `PORT` is the port your application is listening on. ```powershell Invoke-RestMethod "https://localhost:/predict" -Method Post -Body (@{SentimentText="This was a very bad steak"} | ConvertTo-Json) -ContentType "application/json" @@ -201,7 +201,7 @@ Once everything is set up, it's time to test the application. False 0.5 0 ``` -Congratulations! You have successfully served your model to make predictions over the internet using an ASP.NET Core Web API. +Congratulations! You've successfully served your model to make predictions over the internet using an ASP.NET Core Web API. ## Next Steps diff --git a/docs/machine-learning/resources/glossary.md b/docs/machine-learning/resources/glossary.md index 18330498544e4..de9dc85738851 100644 --- a/docs/machine-learning/resources/glossary.md +++ b/docs/machine-learning/resources/glossary.md @@ -106,7 +106,7 @@ A feature extraction scheme for text data: any sequence of N words turns into a ## Normalization -Normalization is the process of scaling floating point data to values between 0 and 1. Many of the training algorithms used in ML.NET require input feature data to be normalized. ML.NET provides a series of [transforms for normalization](transforms.md#normalization-and-scaling) +Normalization is the process of scaling floating point data to values between 0 and 1. Many of the training algorithms used in ML.NET require input feature data to be normalized. ML.NET provides a series of [transforms for normalization](transforms.md#normalization-and-scaling). ## Numerical feature vector diff --git a/docs/machine-learning/resources/improve-machine-learning-model-ml-net.md b/docs/machine-learning/resources/improve-machine-learning-model-ml-net.md index 7b9ed554331fc..83f59e8205d3c 100644 --- a/docs/machine-learning/resources/improve-machine-learning-model-ml-net.md +++ b/docs/machine-learning/resources/improve-machine-learning-model-ml-net.md @@ -35,7 +35,7 @@ For more information about using PFI, see [Explain model predictions using Permu Cross-validation is a training and model evaluation technique that splits the data into several partitions and trains multiple algorithms on these partitions. This technique improves the robustness of the model by holding out data from the training process. In addition to improving performance on unseen observations, in data-constrained environments it can be an effective tool for training models with a smaller dataset. -Visit the following link to learn [how to use cross validation in ML.NET](../how-to-guides/train-machine-learning-model-cross-validation-ml-net.md) +For more information, see [How to use cross validation in ML.NET](../how-to-guides/train-machine-learning-model-cross-validation-ml-net.md). ## Hyperparameter tuning diff --git a/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md b/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md index 07aa0992e3beb..6904aaf082583 100644 --- a/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md +++ b/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md @@ -2,7 +2,7 @@ description: "Learn more about: Troubleshooting Interoperability (Visual Basic)" title: "Troubleshooting Interoperability" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "interop, deploying assemblies" - "assemblies [Visual Basic]" - "interop, installing assemblies that share components" @@ -20,122 +20,122 @@ ms.assetid: b324cc1e-b03c-4f39-aea6-6a6d5bfd0e37 --- # Troubleshooting Interoperability (Visual Basic) -When you interoperate between COM and the managed code of the .NET Framework, you may encounter one or more of the following common issues. - -## Interop Marshalling - - At times, you may have to use data types that are not part of the .NET Framework. Interop assemblies handle most of the work for COM objects, but you may have to control the data types that are used when managed objects are exposed to COM. For example, structures in class libraries must specify the `BStr` unmanaged type on strings sent to COM objects created by Visual Basic 6.0 and earlier versions. In such cases, you can use the attribute to cause managed types to be exposed as unmanaged types. - -## Exporting Fixed-Length Strings to Unmanaged Code - - In Visual Basic 6.0 and earlier versions, strings are exported to COM objects as sequences of bytes without a null termination character. For compatibility with other languages, Visual Basic .NET includes a termination character when exporting strings. The best way to address this incompatibility is to export strings that lack the termination character as arrays of `Byte` or `Char`. - -## Exporting Inheritance Hierarchies - - Managed class hierarchies flatten out when exposed as COM objects. For example, if you define a base class with a member, and then inherit the base class in a derived class that is exposed as a COM object, clients that use the derived class in the COM object will not be able to use the inherited members. Base class members can be accessed from COM objects only as instances of a base class, and then only if the base class is also created as a COM object. - -## Overloaded Methods - - Although you can create overloaded methods with Visual Basic, they are not supported by COM. When a class that contains overloaded methods is exposed as a COM object, new method names are generated for the overloaded methods. - - For example, consider a class that has two overloads of the `Synch` method. When the class is exposed as a COM object, the new generated method names could be `Synch` and `Synch_2`. - - The renaming can cause two problems for consumers of the COM object. - -1. Clients might not expect the generated method names. - -2. The generated method names in the class exposed as a COM object can change when new overloads are added to the class or its base class. This can cause versioning problems. - - To solve both problems, give each method a unique name, instead of using overloading, when you develop objects that will be exposed as COM objects. - -## Use of COM Objects Through Interop Assemblies - - You use interop assemblies almost as if they are managed code replacements for the COM objects they represent. However, because they are wrappers and not actual COM objects, there are some differences between using interop assemblies and standard assemblies. These areas of difference include the exposure of classes, and data types for parameters and return values. - -## Classes Exposed as Both Interfaces and Classes - - Unlike classes in standard assemblies, COM classes are exposed in interop assemblies as both an interface and a class that represents the COM class. The interface's name is identical to that of the COM class. The name of the interop class is the same as that of the original COM class, but with the word "Class" appended. For example, suppose you have a project with a reference to an interop assembly for a COM object. If the COM class is named `MyComClass`, IntelliSense and the Object Browser show an interface named `MyComClass` and a class named `MyComClassClass`. - -## Creating Instances of a .NET Framework Class - - Generally, you create an instance of a .NET Framework class using the `New` statement with a class name. Having a COM class represented by an interop assembly is the one case in which you can use the `New` statement with an interface. Unless you are using the COM class with an `Inherits` statement, you can use the interface just as you would a class. The following code demonstrates how to create a `Command` object in a project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object: - - [!code-vb[VbVbalrInterop#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#20)] - - However, if you are using the COM class as the base for a derived class, you must use the interop class that represents the COM class, as in the following code: - - [!code-vb[VbVbalrInterop#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#21)] - +When you interoperate between COM and the managed code of the .NET Framework, you may encounter one or more of the following common issues. + +## Interop Marshalling + + At times, you may have to use data types that are not part of the .NET Framework. Interop assemblies handle most of the work for COM objects, but you may have to control the data types that are used when managed objects are exposed to COM. For example, structures in class libraries must specify the `BStr` unmanaged type on strings sent to COM objects created by Visual Basic 6.0 and earlier versions. In such cases, you can use the attribute to cause managed types to be exposed as unmanaged types. + +## Exporting Fixed-Length Strings to Unmanaged Code + + In Visual Basic 6.0 and earlier versions, strings are exported to COM objects as sequences of bytes without a null termination character. For compatibility with other languages, Visual Basic .NET includes a termination character when exporting strings. The best way to address this incompatibility is to export strings that lack the termination character as arrays of `Byte` or `Char`. + +## Exporting Inheritance Hierarchies + + Managed class hierarchies flatten out when exposed as COM objects. For example, if you define a base class with a member, and then inherit the base class in a derived class that is exposed as a COM object, clients that use the derived class in the COM object will not be able to use the inherited members. Base class members can be accessed from COM objects only as instances of a base class, and then only if the base class is also created as a COM object. + +## Overloaded Methods + + Although you can create overloaded methods with Visual Basic, they are not supported by COM. When a class that contains overloaded methods is exposed as a COM object, new method names are generated for the overloaded methods. + + For example, consider a class that has two overloads of the `Synch` method. When the class is exposed as a COM object, the new generated method names could be `Synch` and `Synch_2`. + + The renaming can cause two problems for consumers of the COM object. + +1. Clients might not expect the generated method names. + +2. The generated method names in the class exposed as a COM object can change when new overloads are added to the class or its base class. This can cause versioning problems. + + To solve both problems, give each method a unique name, instead of using overloading, when you develop objects that will be exposed as COM objects. + +## Use of COM Objects Through Interop Assemblies + + You use interop assemblies almost as if they are managed code replacements for the COM objects they represent. However, because they are wrappers and not actual COM objects, there are some differences between using interop assemblies and standard assemblies. These areas of difference include the exposure of classes, and data types for parameters and return values. + +## Classes Exposed as Both Interfaces and Classes + + Unlike classes in standard assemblies, COM classes are exposed in interop assemblies as both an interface and a class that represents the COM class. The interface's name is identical to that of the COM class. The name of the interop class is the same as that of the original COM class, but with the word "Class" appended. For example, suppose you have a project with a reference to an interop assembly for a COM object. If the COM class is named `MyComClass`, IntelliSense and the Object Browser show an interface named `MyComClass` and a class named `MyComClassClass`. + +## Creating Instances of a .NET Framework Class + + Generally, you create an instance of a .NET Framework class using the `New` statement with a class name. Having a COM class represented by an interop assembly is the one case in which you can use the `New` statement with an interface. Unless you are using the COM class with an `Inherits` statement, you can use the interface just as you would a class. The following code demonstrates how to create a `Command` object in a project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object: + + [!code-vb[VbVbalrInterop#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#20)] + + However, if you are using the COM class as the base for a derived class, you must use the interop class that represents the COM class, as in the following code: + + [!code-vb[VbVbalrInterop#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#21)] + > [!NOTE] -> Interop assemblies implicitly implement interfaces that represent COM classes. You should not try to use the `Implements` statement to implement these interfaces or an error will result. - -## Data Types for Parameters and Return Values - - Unlike members of standard assemblies, interop assembly members may have data types that differ from those used in the original object declaration. Although interop assemblies implicitly convert COM types to compatible common language runtime types, you should pay attention to the data types that are used by both sides to prevent runtime errors. For example, in COM objects created in Visual Basic 6.0 and earlier versions, values of type `Integer` assume the .NET Framework equivalent type, `Short`. It is recommended that you use the Object Browser to examine the characteristics of imported members before you use them. - -## Module level COM methods - - Most COM objects are used by creating an instance of a COM class using the `New` keyword and then calling methods of the object. One exception to this rule involves COM objects that contain `AppObj` or `GlobalMultiUse` COM classes. Such classes resemble module level methods in Visual Basic .NET classes. Visual Basic 6.0 and earlier versions implicitly create instances of such objects for you the first time that you call one of their methods. For example, in Visual Basic 6.0 you can add a reference to the Microsoft DAO 3.6 Object Library and call the `DBEngine` method without first creating an instance: - -```vb -Dim db As DAO.Database -' Open the database. -Set db = DBEngine.OpenDatabase("C:\nwind.mdb") -' Use the database object. -``` - - Visual Basic .NET requires that you always create instances of COM objects before you can use their methods. To use these methods in Visual Basic, declare a variable of the desired class and use the new keyword to assign the object to the object variable. The `Shared` keyword can be used when you want to make sure that only one instance of the class is created. - - [!code-vb[VbVbalrInterop#23](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#23)] - -## Unhandled Errors in Event Handlers - - One common interop problem involves errors in event handlers that handle events raised by COM objects. Such errors are ignored unless you specifically check for errors using `On Error` or `Try...Catch...Finally` statements. For example, the following example is from a Visual Basic .NET project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object. - - [!code-vb[VbVbalrInterop#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#24)] - - This example raises an error as expected. However, if you try the same example without the `Try...Catch...Finally` block, the error is ignored as if you used the `OnError Resume Next` statement. Without error handling, the division by zero silently fails. Because such errors never raise unhandled exception errors, it is important that you use some form of exception handling in event handlers that handle events from COM objects. - -### Understanding COM interop errors - - Without error handling, interop calls often generate errors that provide little information. Whenever possible, use structured error handling to provide more information about problems when they occur. This can be especially helpful when you debug applications. For example: - - [!code-vb[VbVbalrInterop#25](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#25)] - - You can find information such as the error description, HRESULT, and the source of COM errors by examining the contents of the exception object. - -## ActiveX Control Issues - - Most ActiveX controls that work with Visual Basic 6.0 work with Visual Basic .NET without trouble. The main exceptions are container controls, or controls that visually contain other controls. Some examples of older controls that do not work correctly with Visual Studio are as follows: - -- Microsoft Forms 2.0 Frame control - -- Up-Down control, also known as the spin control - -- Sheridan Tab Control - - There are only a few workarounds for unsupported ActiveX control problems. You can migrate existing controls to Visual Studio if you own the original source code. Otherwise, you can check with software vendors for updated .NET-compatible versions of controls to replace unsupported ActiveX controls. - -## Passing ReadOnly Properties of Controls ByRef - - Visual Basic .NET sometimes raises COM errors such as, "Error 0x800A017F CTL_E_SETNOTSUPPORTED", when you pass `ReadOnly` properties of some older ActiveX controls as `ByRef` parameters to other procedures. Similar procedure calls from Visual Basic 6.0 do not raise an error, and the parameters are treated as if you passed them by value. The Visual Basic .NET error message indicates that you are trying to change a property that does not have a property `Set` procedure. - - If you have access to the procedure being called, you can prevent this error by using the `ByVal` keyword to declare parameters that accept `ReadOnly` properties. For example: - - [!code-vb[VbVbalrInterop#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#26)] - - If you do not have access to the source code for the procedure being called, you can force the property to be passed by value by adding an extra set of brackets around the calling procedure. For example, in a project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object, you can use: - - [!code-vb[VbVbalrInterop#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#27)] - -## Deploying Assemblies That Expose Interop - - Deploying assemblies that expose COM interfaces presents some unique challenges. For example, a potential problem occurs when separate applications reference the same COM assembly. This situation is common when a new version of an assembly is installed and another application is still using the old version of the assembly. If you uninstall an assembly that shares a DLL, you can unintentionally make it unavailable to the other assemblies. - - To avoid this problem, you should install shared assemblies to the Global Assembly Cache (GAC) and use a MergeModule for the component. If you cannot install the application in the GAC, it should be installed to CommonFilesFolder in a version-specific subdirectory. - - Assemblies that are not shared should be located side by side in the directory with the calling application. - +> Interop assemblies implicitly implement interfaces that represent COM classes. You should not try to use the `Implements` statement to implement these interfaces or an error will result. + +## Data Types for Parameters and Return Values + + Unlike members of standard assemblies, interop assembly members may have data types that differ from those used in the original object declaration. Although interop assemblies implicitly convert COM types to compatible common language runtime types, you should pay attention to the data types that are used by both sides to prevent runtime errors. For example, in COM objects created in Visual Basic 6.0 and earlier versions, values of type `Integer` assume the .NET Framework equivalent type, `Short`. It is recommended that you use the Object Browser to examine the characteristics of imported members before you use them. + +## Module level COM methods + + Most COM objects are used by creating an instance of a COM class using the `New` keyword and then calling methods of the object. One exception to this rule involves COM objects that contain `AppObj` or `GlobalMultiUse` COM classes. Such classes resemble module level methods in Visual Basic .NET classes. Visual Basic 6.0 and earlier versions implicitly create instances of such objects for you the first time that you call one of their methods. For example, in Visual Basic 6.0 you can add a reference to the Microsoft DAO 3.6 Object Library and call the `DBEngine` method without first creating an instance: + +```vb +Dim db As DAO.Database +' Open the database. +Set db = DBEngine.OpenDatabase("C:\nwind.mdb") +' Use the database object. +``` + + Visual Basic .NET requires that you always create instances of COM objects before you can use their methods. To use these methods in Visual Basic, declare a variable of the desired class and use the new keyword to assign the object to the object variable. The `Shared` keyword can be used when you want to make sure that only one instance of the class is created. + + [!code-vb[VbVbalrInterop#23](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#23)] + +## Unhandled Errors in Event Handlers + + One common interop problem involves errors in event handlers that handle events raised by COM objects. Such errors are ignored unless you specifically check for errors using `On Error` or `Try...Catch...Finally` statements. For example, the following example is from a Visual Basic .NET project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object. + + [!code-vb[VbVbalrInterop#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#24)] + + This example raises an error as expected. However, if you try the same example without the `Try...Catch...Finally` block, the error is ignored as if you used the `OnError Resume Next` statement. Without error handling, the division by zero silently fails. Because such errors never raise unhandled exception errors, it is important that you use some form of exception handling in event handlers that handle events from COM objects. + +### Understanding COM interop errors + + Without error handling, interop calls often generate errors that provide little information. Whenever possible, use structured error handling to provide more information about problems when they occur. This can be especially helpful when you debug applications. For example: + + [!code-vb[VbVbalrInterop#25](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#25)] + + You can find information such as the error description, HRESULT, and the source of COM errors by examining the contents of the exception object. + +## ActiveX Control Issues + + Most ActiveX controls that work with Visual Basic 6.0 work with Visual Basic .NET without trouble. The main exceptions are container controls, or controls that visually contain other controls. Some examples of older controls that do not work correctly with Visual Studio are as follows: + +- Microsoft Forms 2.0 Frame control + +- Up-Down control, also known as the spin control + +- Sheridan Tab Control + + There are only a few workarounds for unsupported ActiveX control problems. You can migrate existing controls to Visual Studio if you own the original source code. Otherwise, you can check with software vendors for updated .NET-compatible versions of controls to replace unsupported ActiveX controls. + +## Passing ReadOnly Properties of Controls ByRef + + Visual Basic sometimes raises COM errors, such as "Error 0x800A017F CTL_E_SETNOTSUPPORTED", when you pass `ReadOnly` properties of some older ActiveX controls as `ByRef` parameters to other procedures. Similar procedure calls from Visual Basic 6.0 do not raise an error, and the parameters are treated as if you passed them by value. The Visual Basic .NET error message indicates that you are trying to change a property that does not have a property `Set` procedure. + + If you have access to the procedure being called, you can prevent this error by using the `ByVal` keyword to declare parameters that accept `ReadOnly` properties. For example: + + [!code-vb[VbVbalrInterop#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#26)] + + If you do not have access to the source code for the procedure being called, you can force the property to be passed by value by adding an extra set of brackets around the calling procedure. For example, in a project that has a reference to the Microsoft ActiveX Data Objects 2.8 Library COM object, you can use: + + [!code-vb[VbVbalrInterop#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#27)] + +## Deploying Assemblies That Expose Interop + + Deploying assemblies that expose COM interfaces presents some unique challenges. For example, a potential problem occurs when separate applications reference the same COM assembly. This situation is common when a new version of an assembly is installed and another application is still using the old version of the assembly. If you uninstall an assembly that shares a DLL, you can unintentionally make it unavailable to the other assemblies. + + To avoid this problem, you should install shared assemblies to the Global Assembly Cache (GAC) and use a MergeModule for the component. If you cannot install the application in the GAC, it should be installed to CommonFilesFolder in a version-specific subdirectory. + + Assemblies that are not shared should be located side by side in the directory with the calling application. + ## See also -