From 29f9d4457a13440305239b0d54a8fea4ad7c4dc4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:08:15 -0700 Subject: [PATCH 1/2] System.D* --- .../DbBinaryExpression.xml | 4 +- .../DbExpressionVisitor`1.xml | 20 +- .../DbFunctionCommandTree.xml | 10 +- .../DbLimitExpression.xml | 2 +- .../DbSkipExpression.xml | 4 +- .../DbUnaryExpression.xml | 2 +- xml/System.Data.Common/DBDataPermission.xml | 8 +- xml/System.Data.Common/DataAdapter.xml | 80 +- xml/System.Data.Common/DataColumnMapping.xml | 108 +-- .../DataColumnMappingCollection.xml | 390 ++++---- xml/System.Data.Common/DataTableMapping.xml | 196 ++-- .../DataTableMappingCollection.xml | 390 ++++---- xml/System.Data.Common/DbBatch.xml | 8 +- xml/System.Data.Common/DbCommand.xml | 30 +- xml/System.Data.Common/DbCommandBuilder.xml | 86 +- xml/System.Data.Common/DbConnection.xml | 26 +- .../DbConnectionStringBuilder.xml | 60 +- xml/System.Data.Common/DbDataAdapter.xml | 368 ++++---- xml/System.Data.Common/DbDataReader.xml | 14 +- xml/System.Data.Common/DbDataRecord.xml | 270 +++--- xml/System.Data.Common/DbDataSource.xml | 8 +- xml/System.Data.Common/DbEnumerator.xml | 44 +- xml/System.Data.Common/DbParameter.xml | 30 +- .../DbParameterCollection.xml | 4 +- .../DbProviderFactories.xml | 84 +- xml/System.Data.Common/DbTransaction.xml | 78 +- .../RowUpdatedEventArgs.xml | 8 +- .../RowUpdatingEventArgs.xml | 4 +- .../TypedDataSetGeneratorException.xml | 12 +- .../EntityModelBuildProvider.xml | 10 +- .../PluralizationService.xml | 78 +- .../EntityConnection.xml | 44 +- .../EntityConnectionStringBuilder.xml | 18 +- .../EntityDataReader.xml | 18 +- .../AssociationAttribute.xml | 4 +- .../ColumnAttribute.xml | 16 +- .../InheritanceMappingAttribute.xml | 4 +- .../MetaDataMember.xml | 4 +- .../ParameterAttribute.xml | 10 +- .../TableAttribute.xml | 4 +- .../ChangeConflictCollection.xml | 82 +- xml/System.Data.Linq/CompiledQuery.xml | 334 +++---- xml/System.Data.Linq/DataContext.xml | 56 +- xml/System.Data.Linq/DataLoadOptions.xml | 2 +- xml/System.Data.Linq/EntityRef`1.xml | 20 +- xml/System.Data.Linq/EntitySet`1.xml | 198 ++-- ...gnKeyReferenceAlreadyHasValueException.xml | 12 +- xml/System.Data.Linq/IMultipleResults.xml | 64 +- xml/System.Data.Linq/ITable.xml | 12 +- xml/System.Data.Linq/ITable`1.xml | 40 +- xml/System.Data.Linq/Link`1.xml | 6 +- xml/System.Data.Linq/MemberChangeConflict.xml | 90 +- xml/System.Data.Linq/RefreshMode.xml | 40 +- xml/System.Data.Linq/Table`1.xml | 584 ++++++------ xml/System.Data.Metadata.Edm/Facet.xml | 12 +- .../MetadataProperty.xml | 2 +- .../NavigationProperty.xml | 22 +- .../PrimitiveType.xml | 24 +- .../ComplexObject.xml | 12 +- ...elationshipNavigationPropertyAttribute.xml | 4 +- .../EdmScalarPropertyAttribute.xml | 42 +- .../EdmSchemaAttribute.xml | 20 +- .../EntityCollection`1.xml | 88 +- .../EntityObject.xml | 14 +- .../EntityReference.xml | 24 +- .../EntityReference`1.xml | 28 +- .../IEntityChangeTracker.xml | 8 +- .../IRelatedEnd.xml | 56 +- .../RelatedEnd.xml | 54 +- .../RelationshipManager.xml | 14 +- xml/System.Data.Objects/CompiledQuery.xml | 4 +- xml/System.Data.Objects/IObjectSet`1.xml | 40 +- xml/System.Data.Objects/MergeOption.xml | 2 +- xml/System.Data.Objects/ObjectContext.xml | 178 ++-- .../ObjectContextOptions.xml | 10 +- xml/System.Data.Objects/ObjectParameter.xml | 2 +- .../ObjectParameterCollection.xml | 10 +- xml/System.Data.Objects/ObjectQuery.xml | 22 +- xml/System.Data.Objects/ObjectQuery`1.xml | 108 +-- xml/System.Data.Objects/ObjectResult`1.xml | 8 +- xml/System.Data.Objects/ObjectSet`1.xml | 70 +- .../ObjectStateManager.xml | 22 +- xml/System.Data.Odbc/OdbcCommand.xml | 70 +- xml/System.Data.Odbc/OdbcCommandBuilder.xml | 66 +- xml/System.Data.Odbc/OdbcConnection.xml | 64 +- .../OdbcConnectionStringBuilder.xml | 18 +- xml/System.Data.Odbc/OdbcDataAdapter.xml | 56 +- xml/System.Data.Odbc/OdbcDataReader.xml | 72 +- xml/System.Data.Odbc/OdbcException.xml | 6 +- .../OdbcInfoMessageEventArgs.xml | 2 +- xml/System.Data.Odbc/OdbcParameter.xml | 46 +- .../OdbcParameterCollection.xml | 10 +- xml/System.Data.Odbc/OdbcPermission.xml | 2 +- .../OdbcRowUpdatedEventArgs.xml | 42 +- .../OdbcRowUpdatingEventArgs.xml | 42 +- xml/System.Data.Odbc/OdbcTransaction.xml | 98 +- xml/System.Data.OleDb/OleDbCommand.xml | 88 +- xml/System.Data.OleDb/OleDbCommandBuilder.xml | 66 +- xml/System.Data.OleDb/OleDbConnection.xml | 74 +- .../OleDbConnectionStringBuilder.xml | 26 +- xml/System.Data.OleDb/OleDbDataAdapter.xml | 88 +- xml/System.Data.OleDb/OleDbDataReader.xml | 72 +- xml/System.Data.OleDb/OleDbError.xml | 112 +-- xml/System.Data.OleDb/OleDbException.xml | 70 +- .../OleDbInfoMessageEventArgs.xml | 6 +- xml/System.Data.OleDb/OleDbParameter.xml | 60 +- .../OleDbParameterCollection.xml | 4 +- xml/System.Data.OleDb/OleDbPermission.xml | 2 +- .../OleDbRowUpdatedEventArgs.xml | 42 +- .../OleDbRowUpdatingEventArgs.xml | 42 +- xml/System.Data.OleDb/OleDbSchemaGuid.xml | 882 +++++++++--------- xml/System.Data.OleDb/OleDbTransaction.xml | 104 +-- xml/System.Data.OracleClient/OracleBFile.xml | 38 +- xml/System.Data.OracleClient/OracleBinary.xml | 16 +- .../OracleBoolean.xml | 16 +- .../OracleCommand.xml | 56 +- .../OracleCommandBuilder.xml | 64 +- .../OracleConnection.xml | 62 +- .../OracleConnectionStringBuilder.xml | 36 +- .../OracleDataAdapter.xml | 34 +- .../OracleDataReader.xml | 90 +- .../OracleDateTime.xml | 96 +- xml/System.Data.OracleClient/OracleLob.xml | 38 +- .../OracleMonthSpan.xml | 100 +- xml/System.Data.OracleClient/OracleNumber.xml | 232 ++--- .../OracleParameter.xml | 44 +- .../OracleParameterCollection.xml | 6 +- .../OraclePermission.xml | 4 +- .../OraclePermissionAttribute.xml | 2 +- .../OracleRowUpdatedEventArgs.xml | 72 +- .../OracleRowUpdatingEventArgs.xml | 72 +- xml/System.Data.OracleClient/OracleString.xml | 16 +- .../OracleTimeSpan.xml | 92 +- .../OracleTransaction.xml | 102 +- .../ChangeOperationResponse.xml | 212 ++--- .../DataServiceClientException.xml | 12 +- .../DataServiceCollection`1.xml | 50 +- .../DataServiceContext.xml | 100 +- .../DataServiceQuery.xml | 48 +- .../DataServiceQueryException.xml | 14 +- .../DataServiceQuery`1.xml | 18 +- .../DataServiceRequestArgs.xml | 2 +- .../DataServiceRequestException.xml | 12 +- .../DataServiceRequest`1.xml | 200 ++-- .../DataServiceStreamResponse.xml | 12 +- .../EntityChangedParams.xml | 22 +- .../EntityCollectionChangedParams.xml | 32 +- .../EntityDescriptor.xml | 6 +- .../LinkDescriptor.xml | 22 +- .../MediaEntryAttribute.xml | 2 +- .../MimeTypePropertyAttribute.xml | 14 +- .../QueryOperationResponse.xml | 24 +- .../QueryOperationResponse`1.xml | 24 +- .../TrackingMode.xml | 14 +- .../EntityPropertyMappingAttribute.xml | 16 +- .../SyndicationTextContentKind.xml | 10 +- .../IDataServiceMetadataProvider.xml | 18 +- .../IDataServicePagingProvider.xml | 20 +- .../IDataServiceStreamProvider.xml | 24 +- .../OpenTypeMethods.xml | 90 +- .../ResourceProperty.xml | 6 +- .../ResourceType.xml | 20 +- .../DataServiceConfiguration.xml | 12 +- .../DataServiceException.xml | 8 +- xml/System.Data.Services/DataService`1.xml | 74 +- xml/System.Data.Services/ExpandSegment.xml | 48 +- .../HandleExceptionArgs.xml | 40 +- .../IDataServiceConfiguration.xml | 2 +- xml/System.Data.Services/IExpandProvider.xml | 14 +- xml/System.Data.Services/IUpdatable.xml | 90 +- .../SqlDataSourceEnumerator.xml | 2 +- .../SqlNotificationRequest.xml | 2 +- xml/System.Data.SqlClient/SqlBulkCopy.xml | 54 +- .../SqlBulkCopyColumnMapping.xml | 12 +- .../SqlBulkCopyColumnMappingCollection.xml | 288 +++--- .../SqlBulkCopyOptions.xml | 2 +- .../SqlClientPermission.xml | 4 +- .../SqlColumnEncryptionCngProvider.xml | 2 +- .../SqlColumnEncryptionCspProvider.xml | 2 +- .../SqlColumnEncryptionKeyStoreProvider.xml | 4 +- xml/System.Data.SqlClient/SqlCommand.xml | 190 ++-- .../SqlCommandBuilder.xml | 64 +- xml/System.Data.SqlClient/SqlConnection.xml | 118 +-- .../SqlConnectionStringBuilder.xml | 24 +- xml/System.Data.SqlClient/SqlDataAdapter.xml | 76 +- xml/System.Data.SqlClient/SqlDataReader.xml | 90 +- xml/System.Data.SqlClient/SqlDependency.xml | 12 +- xml/System.Data.SqlClient/SqlError.xml | 228 ++--- xml/System.Data.SqlClient/SqlException.xml | 2 +- .../SqlInfoMessageEventArgs.xml | 4 +- xml/System.Data.SqlClient/SqlParameter.xml | 60 +- .../SqlParameterCollection.xml | 20 +- .../SqlRowUpdatedEventArgs.xml | 72 +- .../SqlRowUpdatingEventArgs.xml | 72 +- .../SqlRowsCopiedEventArgs.xml | 4 +- xml/System.Data.SqlClient/SqlTransaction.xml | 204 ++-- xml/System.Data.SqlTypes/SqlBinary.xml | 14 +- xml/System.Data.SqlTypes/SqlBoolean.xml | 308 +++--- xml/System.Data.SqlTypes/SqlByte.xml | 168 ++-- xml/System.Data.SqlTypes/SqlBytes.xml | 8 +- xml/System.Data.SqlTypes/SqlChars.xml | 10 +- xml/System.Data.SqlTypes/SqlDateTime.xml | 138 +-- xml/System.Data.SqlTypes/SqlDecimal.xml | 10 +- xml/System.Data.SqlTypes/SqlDouble.xml | 162 ++-- xml/System.Data.SqlTypes/SqlFileStream.xml | 2 +- xml/System.Data.SqlTypes/SqlGuid.xml | 140 +-- xml/System.Data.SqlTypes/SqlInt16.xml | 30 +- xml/System.Data.SqlTypes/SqlInt32.xml | 178 ++-- xml/System.Data.SqlTypes/SqlInt64.xml | 178 ++-- xml/System.Data.SqlTypes/SqlMoney.xml | 178 ++-- .../SqlNullValueException.xml | 10 +- xml/System.Data.SqlTypes/SqlSingle.xml | 20 +- xml/System.Data.SqlTypes/SqlString.xml | 228 ++--- .../SqlTruncateException.xml | 4 +- xml/System.Data.SqlTypes/SqlTypeException.xml | 14 +- xml/System.Data.SqlTypes/SqlXml.xml | 70 +- xml/System.Data/AcceptRejectRule.xml | 24 +- xml/System.Data/Constraint.xml | 6 +- xml/System.Data/ConstraintCollection.xml | 38 +- xml/System.Data/DBConcurrencyException.xml | 8 +- xml/System.Data/DataColumn.xml | 60 +- xml/System.Data/DataColumnCollection.xml | 40 +- xml/System.Data/DataReaderExtensions.xml | 86 +- xml/System.Data/DataRelation.xml | 14 +- xml/System.Data/DataRelationCollection.xml | 4 +- xml/System.Data/DataRow.xml | 170 ++-- xml/System.Data/DataRowChangeEventArgs.xml | 66 +- xml/System.Data/DataRowCollection.xml | 48 +- xml/System.Data/DataRowComparer.xml | 4 +- xml/System.Data/DataRowComparer`1.xml | 8 +- xml/System.Data/DataRowExtensions.xml | 56 +- xml/System.Data/DataRowState.xml | 2 +- xml/System.Data/DataRowVersion.xml | 16 +- xml/System.Data/DataRowView.xml | 24 +- xml/System.Data/DataSet.xml | 348 +++---- xml/System.Data/DataSetDateTime.xml | 4 +- xml/System.Data/DataTable.xml | 340 +++---- xml/System.Data/DataTableCollection.xml | 44 +- xml/System.Data/DataTableExtensions.xml | 34 +- xml/System.Data/DataTableReader.xml | 66 +- xml/System.Data/DataView.xml | 56 +- xml/System.Data/DataViewManager.xml | 330 +++---- xml/System.Data/DataViewRowState.xml | 4 +- xml/System.Data/DataViewSetting.xml | 4 +- xml/System.Data/DataViewSettingCollection.xml | 2 +- .../DeletedRowInaccessibleException.xml | 12 +- xml/System.Data/EntityKey.xml | 14 +- xml/System.Data/EntityKeyMember.xml | 20 +- xml/System.Data/EntityState.xml | 2 +- xml/System.Data/EnumerableRowCollection.xml | 24 +- .../EnumerableRowCollectionExtensions.xml | 144 +-- xml/System.Data/EnumerableRowCollection`1.xml | 42 +- xml/System.Data/ForeignKeyConstraint.xml | 10 +- xml/System.Data/IColumnMapping.xml | 2 +- xml/System.Data/IColumnMappingCollection.xml | 80 +- xml/System.Data/IDataAdapter.xml | 56 +- xml/System.Data/IDataParameter.xml | 8 +- xml/System.Data/IDataParameterCollection.xml | 38 +- xml/System.Data/IDataReader.xml | 20 +- xml/System.Data/IDataRecord.xml | 14 +- xml/System.Data/IDbCommand.xml | 22 +- xml/System.Data/IDbConnection.xml | 16 +- xml/System.Data/IDbDataAdapter.xml | 26 +- xml/System.Data/IDbTransaction.xml | 106 +-- xml/System.Data/ITableMapping.xml | 4 +- xml/System.Data/ITableMappingCollection.xml | 52 +- .../InvalidConstraintException.xml | 26 +- xml/System.Data/MappingType.xml | 2 +- xml/System.Data/MissingMappingAction.xml | 10 +- .../MissingPrimaryKeyException.xml | 18 +- xml/System.Data/NoNullAllowedException.xml | 26 +- xml/System.Data/OperationAbortedException.xml | 10 +- .../OrderedEnumerableRowCollection`1.xml | 14 +- xml/System.Data/ReadOnlyException.xml | 18 +- xml/System.Data/RowNotInTableException.xml | 48 +- xml/System.Data/Rule.xml | 4 +- xml/System.Data/TypedTableBaseExtensions.xml | 24 +- xml/System.Data/UniqueConstraint.xml | 2 +- xml/System.Data/XmlReadMode.xml | 24 +- xml/System.Data/XmlWriteMode.xml | 10 +- xml/System.Device.Location/CivicAddress.xml | 98 +- .../CivicAddressResolver.xml | 98 +- xml/System.Device.Location/GeoCoordinate.xml | 14 +- .../GeoCoordinateWatcher.xml | 44 +- .../GeoPositionStatusChangedEventArgs.xml | 10 +- .../ICivicAddressResolver.xml | 46 +- .../IGeoPositionWatcher`1.xml | 18 +- .../SuppressMessageAttribute.xml | 2 +- .../ContractHelper.xml | 20 +- xml/System.Diagnostics.Contracts/Contract.xml | 44 +- .../ContractArgumentValidatorAttribute.xml | 56 +- .../ContractClassAttribute.xml | 38 +- .../ContractClassForAttribute.xml | 38 +- .../ContractFailedEventArgs.xml | 4 +- .../ContractInvariantMethodAttribute.xml | 10 +- .../ContractOptionAttribute.xml | 2 +- .../EventLogConfiguration.xml | 16 +- .../EventLogReader.xml | 8 +- .../EventDescriptor.xml | 60 +- .../EventProvider+WriteEventErrorCode.xml | 14 +- .../EventProvider.xml | 22 +- .../EventProviderTraceListener.xml | 2 +- .../CounterData.xml | 8 +- .../CounterSet.xml | 108 +-- .../CounterSetInstance.xml | 40 +- .../CounterSetInstanceCounterDataSet.xml | 2 +- .../ISymbolBinder.xml | 22 +- .../ISymbolBinder1.xml | 24 +- .../ISymbolDocumentWriter.xml | 4 +- .../ISymbolMethod.xml | 78 +- .../ISymbolWriter.xml | 172 ++-- .../SymBinder.xml | 52 +- .../SymDocument.xml | 66 +- .../SymDocumentType.xml | 4 +- .../SymDocumentWriter.xml | 38 +- .../SymLanguageType.xml | 4 +- .../SymLanguageVendor.xml | 4 +- .../SymMethod.xml | 82 +- .../SymReader.xml | 80 +- .../SymScope.xml | 50 +- .../SymVariable.xml | 88 +- .../SymWriter.xml | 10 +- .../SymbolToken.xml | 4 +- .../EventAttribute.xml | 6 +- .../EventCommandEventArgs.xml | 20 +- .../EventDataAttribute.xml | 20 +- .../EventIgnoreAttribute.xml | 10 +- .../EventListener.xml | 90 +- .../EventSource.xml | 84 +- .../EventSourceAttribute.xml | 2 +- .../PollingCounter.xml | 6 +- xml/System.Diagnostics/Activity.xml | 18 +- xml/System.Diagnostics/BooleanSwitch.xml | 6 +- .../ConditionalAttribute.xml | 2 +- .../ConsoleTraceListener.xml | 20 +- xml/System.Diagnostics/CorrelationManager.xml | 8 +- .../CounterCreationData.xml | 10 +- .../CounterCreationDataCollection.xml | 16 +- xml/System.Diagnostics/CounterSample.xml | 8 +- .../CounterSampleCalculator.xml | 6 +- .../DataReceivedEventArgs.xml | 12 +- .../DataReceivedEventHandler.xml | 6 +- xml/System.Diagnostics/Debug.xml | 178 ++-- .../DebuggableAttribute.xml | 10 +- xml/System.Diagnostics/Debugger.xml | 8 +- .../DebuggerBrowsableAttribute.xml | 4 +- .../DebuggerDisplayAttribute.xml | 2 +- .../DebuggerTypeProxyAttribute.xml | 2 +- .../DefaultTraceListener.xml | 28 +- .../DelimitedListTraceListener.xml | 16 +- xml/System.Diagnostics/DiagnosticListener.xml | 18 +- .../DiagnosticsConfigurationHandler.xml | 44 +- .../EntryWrittenEventArgs.xml | 10 +- xml/System.Diagnostics/EventInstance.xml | 20 +- xml/System.Diagnostics/EventLog.xml | 376 ++++---- xml/System.Diagnostics/EventLogEntry.xml | 18 +- .../EventLogEntryCollection.xml | 10 +- xml/System.Diagnostics/EventLogInstaller.xml | 76 +- .../EventLogTraceListener.xml | 34 +- .../EventSchemaTraceListener.xml | 34 +- .../EventSourceCreationData.xml | 56 +- xml/System.Diagnostics/EventTypeFilter.xml | 2 +- xml/System.Diagnostics/FileVersionInfo.xml | 154 +-- .../InstanceDataCollection.xml | 8 +- .../InstanceDataCollectionCollection.xml | 8 +- .../MonitoringDescriptionAttribute.xml | 2 +- xml/System.Diagnostics/OverflowAction.xml | 2 +- xml/System.Diagnostics/PerformanceCounter.xml | 106 +-- .../PerformanceCounterCategory.xml | 56 +- .../PerformanceCounterInstanceLifetime.xml | 2 +- .../PresentationTraceSources.xml | 122 +-- xml/System.Diagnostics/Process.xml | 416 ++++----- xml/System.Diagnostics/ProcessModule.xml | 18 +- .../ProcessPriorityClass.xml | 14 +- xml/System.Diagnostics/ProcessStartInfo.xml | 82 +- xml/System.Diagnostics/ProcessThread.xml | 24 +- xml/System.Diagnostics/SourceFilter.xml | 6 +- xml/System.Diagnostics/SourceSwitch.xml | 4 +- xml/System.Diagnostics/StackFrame.xml | 26 +- xml/System.Diagnostics/StackTrace.xml | 4 +- xml/System.Diagnostics/Stopwatch.xml | 58 +- xml/System.Diagnostics/Switch.xml | 20 +- xml/System.Diagnostics/SwitchAttribute.xml | 4 +- .../SwitchLevelAttribute.xml | 2 +- .../TextWriterTraceListener.xml | 24 +- xml/System.Diagnostics/Trace.xml | 172 ++-- xml/System.Diagnostics/TraceEventCache.xml | 8 +- xml/System.Diagnostics/TraceEventType.xml | 10 +- xml/System.Diagnostics/TraceFilter.xml | 4 +- xml/System.Diagnostics/TraceListener.xml | 24 +- .../TraceListenerCollection.xml | 30 +- .../TraceLogRetentionOption.xml | 4 +- xml/System.Diagnostics/TraceOptions.xml | 2 +- xml/System.Diagnostics/TraceSource.xml | 68 +- xml/System.Diagnostics/TraceSwitch.xml | 34 +- .../UnescapedXmlDiagnosticData.xml | 4 +- .../XmlWriterTraceListener.xml | 32 +- .../AuthenticablePrincipal.xml | 18 +- .../ComputerPrincipal.xml | 6 +- .../GroupPrincipal.xml | 4 +- .../MultipleMatchesException.xml | 4 +- .../NoMatchingPrincipalException.xml | 2 +- .../PasswordException.xml | 2 +- .../Principal.xml | 6 +- .../PrincipalCollection.xml | 300 +++--- .../PrincipalContext.xml | 4 +- .../PrincipalExistsException.xml | 2 +- .../PrincipalOperationException.xml | 4 +- .../PrincipalSearcher.xml | 6 +- .../PrincipalServerDownException.xml | 8 +- .../UserPrincipal.xml | 4 +- .../ActiveDirectoryInterSiteTransport.xml | 10 +- .../ActiveDirectorySchedule.xml | 6 +- .../ActiveDirectorySchemaClass.xml | 30 +- .../ActiveDirectorySchemaProperty.xml | 36 +- .../ActiveDirectorySite.xml | 20 +- .../AdamInstance.xml | 2 +- .../Domain.xml | 12 +- .../DomainController.xml | 40 +- .../Forest.xml | 8 +- .../ReplicationCursor.xml | 10 +- .../SyncUpdateCallback.xml | 22 +- .../TopLevelNameCollisionOptions.xml | 14 +- .../AddRequest.xml | 2 +- .../DirectoryAttribute.xml | 2 +- .../DirectoryAttributeModification.xml | 22 +- .../DsmlRequestDocument.xml | 2 +- .../DsmlResponseDocument.xml | 2 +- .../DsmlSoapConnection.xml | 6 +- .../DsmlSoapHttpConnection.xml | 2 +- .../PartialResultProcessing.xml | 18 +- .../ActiveDirectorySecurity.xml | 50 +- .../DirectoryEntries.xml | 6 +- .../DirectoryEntry.xml | 66 +- .../DirectorySearcher.xml | 50 +- .../PropertyCollection.xml | 30 +- .../PropertyValueCollection.xml | 98 +- .../SchemaNameCollection.xml | 10 +- xml/System.DirectoryServices/SearchResult.xml | 16 +- .../SearchResultCollection.xml | 24 +- .../IPropertyValueUIService.xml | 50 +- xml/System.Drawing.Design/IToolboxService.xml | 36 +- xml/System.Drawing.Design/IToolboxUser.xml | 58 +- xml/System.Drawing.Design/IconEditor.xml | 50 +- xml/System.Drawing.Design/ImageEditor.xml | 78 +- .../PropertyValueUIItemInvokeHandler.xml | 2 +- xml/System.Drawing.Design/ToolboxItem.xml | 54 +- .../ToolboxItemCollection.xml | 70 +- .../ToolboxItemContainer.xml | 4 +- .../ToolboxItemCreator.xml | 34 +- .../ToolboxItemCreatorCallback.xml | 28 +- xml/System.Drawing.Design/ToolboxService.xml | 32 +- xml/System.Drawing.Design/UITypeEditor.xml | 14 +- .../AdjustableArrowCap.xml | 12 +- xml/System.Drawing.Drawing2D/Blend.xml | 100 +- xml/System.Drawing.Drawing2D/ColorBlend.xml | 4 +- .../CustomLineCap.xml | 12 +- xml/System.Drawing.Drawing2D/DashStyle.xml | 2 +- xml/System.Drawing.Drawing2D/GraphicsPath.xml | 188 ++-- .../GraphicsPathIterator.xml | 44 +- xml/System.Drawing.Drawing2D/HatchBrush.xml | 4 +- .../LinearGradientBrush.xml | 42 +- xml/System.Drawing.Drawing2D/Matrix.xml | 20 +- .../PathGradientBrush.xml | 50 +- xml/System.Drawing.Drawing2D/RegionData.xml | 2 +- xml/System.Drawing.Drawing2D/WarpMode.xml | 10 +- xml/System.Drawing.Drawing2D/WrapMode.xml | 24 +- xml/System.Drawing.Imaging/BitmapData.xml | 52 +- xml/System.Drawing.Imaging/ColorMatrix.xml | 4 +- .../EncoderParameter.xml | 6 +- .../EncoderParameterValueType.xml | 4 +- .../EncoderParameters.xml | 2 +- xml/System.Drawing.Imaging/EncoderValue.xml | 10 +- .../ImageAttributes.xml | 108 +-- xml/System.Drawing.Imaging/ImageCodecInfo.xml | 6 +- xml/System.Drawing.Imaging/ImageFormat.xml | 4 +- xml/System.Drawing.Imaging/ImageLockMode.xml | 14 +- xml/System.Drawing.Imaging/Metafile.xml | 6 +- xml/System.Drawing.Imaging/PropertyItem.xml | 18 +- .../InvalidPrinterException.xml | 34 +- xml/System.Drawing.Printing/Margins.xml | 194 ++-- xml/System.Drawing.Printing/PageSettings.xml | 24 +- xml/System.Drawing.Printing/PaperSize.xml | 22 +- xml/System.Drawing.Printing/PaperSource.xml | 10 +- .../PreviewPrintController.xml | 22 +- xml/System.Drawing.Printing/PrintAction.xml | 14 +- .../PrintController.xml | 22 +- xml/System.Drawing.Printing/PrintDocument.xml | 34 +- .../PrintEventArgs.xml | 2 +- .../PrintPageEventArgs.xml | 8 +- .../PrinterResolution.xml | 8 +- .../PrinterSettings+PaperSizeCollection.xml | 12 +- .../PrinterSettings+PaperSourceCollection.xml | 10 +- ...erSettings+PrinterResolutionCollection.xml | 6 +- .../PrinterSettings+StringCollection.xml | 2 +- .../PrinterSettings.xml | 72 +- .../PrintingPermission.xml | 50 +- .../StandardPrintController.xml | 94 +- xml/System.Drawing.Text/FontCollection.xml | 4 +- .../PrivateFontCollection.xml | 4 +- xml/System.Drawing.Text/TextRenderingHint.xml | 28 +- xml/System.Drawing/Bitmap.xml | 42 +- xml/System.Drawing/Brush.xml | 6 +- xml/System.Drawing/BufferedGraphics.xml | 18 +- .../BufferedGraphicsContext.xml | 20 +- .../BufferedGraphicsManager.xml | 4 +- xml/System.Drawing/CharacterRange.xml | 100 +- xml/System.Drawing/Color.xml | 48 +- xml/System.Drawing/ColorConverter.xml | 6 +- xml/System.Drawing/ContentAlignment.xml | 14 +- xml/System.Drawing/CopyPixelOperation.xml | 10 +- xml/System.Drawing/Font.xml | 30 +- .../FontConverter+FontNameConverter.xml | 10 +- xml/System.Drawing/FontConverter.xml | 6 +- xml/System.Drawing/FontFamily.xml | 6 +- .../Graphics+DrawImageAbort.xml | 94 +- .../Graphics+EnumerateMetafileProc.xml | 24 +- xml/System.Drawing/Graphics.xml | 422 ++++----- xml/System.Drawing/GraphicsUnit.xml | 18 +- xml/System.Drawing/IDeviceContext.xml | 34 +- xml/System.Drawing/Icon.xml | 22 +- xml/System.Drawing/IconConverter.xml | 2 +- xml/System.Drawing/Image.xml | 56 +- xml/System.Drawing/ImageConverter.xml | 40 +- xml/System.Drawing/ImageFormatConverter.xml | 72 +- xml/System.Drawing/Pen.xml | 30 +- xml/System.Drawing/Point.xml | 258 ++--- xml/System.Drawing/PointConverter.xml | 64 +- xml/System.Drawing/PointF.xml | 32 +- xml/System.Drawing/Rectangle.xml | 36 +- xml/System.Drawing/RectangleConverter.xml | 30 +- xml/System.Drawing/RectangleF.xml | 18 +- xml/System.Drawing/Region.xml | 84 +- xml/System.Drawing/Size.xml | 24 +- xml/System.Drawing/SizeConverter.xml | 30 +- xml/System.Drawing/SizeF.xml | 130 +-- xml/System.Drawing/StringAlignment.xml | 2 +- xml/System.Drawing/StringFormat.xml | 64 +- xml/System.Drawing/StringFormatFlags.xml | 60 +- xml/System.Drawing/SystemBrushes.xml | 2 +- xml/System.Drawing/SystemColors.xml | 4 +- xml/System.Drawing/SystemFonts.xml | 8 +- xml/System.Drawing/SystemIcons.xml | 2 +- xml/System.Drawing/TextureBrush.xml | 6 +- xml/System.Drawing/ToolboxBitmapAttribute.xml | 180 ++-- xml/System.Dynamic/DynamicMetaObject.xml | 28 +- xml/System.Dynamic/DynamicObject.xml | 670 ++++++------- .../IDynamicMetaObjectProvider.xml | 14 +- 548 files changed, 13270 insertions(+), 13270 deletions(-) diff --git a/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml b/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml index 0c3d5d83c90..399cdad20b7 100644 --- a/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml @@ -48,7 +48,7 @@ property is set. For example, requires that its left expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + Derived expression types might perform stricter type checks when the property is set. For example, requires that its left expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. ]]> @@ -87,7 +87,7 @@ property is set. For example, requires that its right expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + Derived expression types might perform stricter type checks when the property is set. For example, requires that its right expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbExpressionVisitor`1.xml b/xml/System.Data.Common.CommandTrees/DbExpressionVisitor`1.xml index 1093182ba69..b85cb9714c6 100644 --- a/xml/System.Data.Common.CommandTrees/DbExpressionVisitor`1.xml +++ b/xml/System.Data.Common.CommandTrees/DbExpressionVisitor`1.xml @@ -21,11 +21,11 @@ The type of the result produced by the visitor. Defines the basic functionality that should be implemented by visitors that return a result value of a specific type. - is an abstract class that describes expression traversal. - + is an abstract class that describes expression traversal. + ]]> @@ -425,11 +425,11 @@ When overridden in a derived class, handles any expression of an unrecognized type. A result value of a specific type. - diff --git a/xml/System.Data.Common.CommandTrees/DbFunctionCommandTree.xml b/xml/System.Data.Common.CommandTrees/DbFunctionCommandTree.xml index 5564c9f7c10..f4300190cbf 100644 --- a/xml/System.Data.Common.CommandTrees/DbFunctionCommandTree.xml +++ b/xml/System.Data.Common.CommandTrees/DbFunctionCommandTree.xml @@ -73,11 +73,11 @@ Gets the expected result type for the function's first result set. The expected result type for the function's first result set. - within a row indicate the expected type for columns with the corresponding names. The result type does not constrain the order of columns. - + within a row indicate the expected type for columns with the corresponding names. The result type does not constrain the order of columns. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml b/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml index fe441ea52a0..0a0acabc7c6 100644 --- a/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml @@ -20,7 +20,7 @@ can be applied to any with a collection result type, including . provides the equivalent of the Top operation. It does not require an ordering operation to have been performed on its input. It has two `Expression` properties, and , that specify the collection and the number of rows to return respectively. also has a `Boolean` property that controls whether rows equal in rank to the final row are returned. defaults to `false`. + A can be applied to any with a collection result type, including . provides the equivalent of the Top operation. It does not require an ordering operation to have been performed on its input. It has two `Expression` properties, and , that specify the collection and the number of rows to return respectively. also has a `Boolean` property that controls whether rows equal in rank to the final row are returned. defaults to `false`. ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml b/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml index e180e086a6e..7f27a661331 100644 --- a/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml @@ -20,7 +20,7 @@ requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. + requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. ]]> @@ -174,7 +174,7 @@ requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. + requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml b/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml index 8df42a29358..efaef136e90 100644 --- a/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml @@ -55,7 +55,7 @@ property is set. For example, requires that its argument expression has a collection result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + Derived expression types might perform stricter type checks when the property is set. For example, requires that its argument expression has a collection result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. ]]> diff --git a/xml/System.Data.Common/DBDataPermission.xml b/xml/System.Data.Common/DBDataPermission.xml index 6e1072ab919..af745152030 100644 --- a/xml/System.Data.Common/DBDataPermission.xml +++ b/xml/System.Data.Common/DBDataPermission.xml @@ -272,7 +272,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> @@ -376,7 +376,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> @@ -729,7 +729,7 @@ and methods to make the objects security encodable. + Custom code that extends security objects must implement the and methods to make the objects security encodable. ]]> @@ -777,7 +777,7 @@ is a permission that represents all the operations permitted by both the current permission object and the specified permission object. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations permitted by both the current permission object and the specified permission object. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Data.Common/DataAdapter.xml b/xml/System.Data.Common/DataAdapter.xml index 17801b681e1..8b8d3ef96b1 100644 --- a/xml/System.Data.Common/DataAdapter.xml +++ b/xml/System.Data.Common/DataAdapter.xml @@ -67,7 +67,7 @@ serves as a bridge between a and a data source for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the . + The serves as a bridge between a and a data source for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the . If you are connecting to a SQL Server database, you can increase overall performance by using the along with its associated and objects. For OLE DB-supported data sources, use the with its associated and objects. For ODBC-supported data sources, use the with its associated and objects. For Oracle databases, use the with its associated and objects. @@ -132,9 +132,9 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| -||An array of objects.| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| +||An array of objects.| You can change the value of any of these properties through a separate call to the property. @@ -254,7 +254,7 @@ is not called, and the newly added rows are treated as inserted rows. + If `false`, is not called, and the newly added rows are treated as inserted rows. ]]> @@ -310,10 +310,10 @@ being updated. By default, ADO.NET calls the `AcceptChanges` method of the `DataRow` after the update. However, if you want to merge the updated row back into another , you may want to preserver the original value of a primary key column. For example, a primary key column corresponding to an automatically incrementing column in the database, such as an identity column, can contain new values that are assigned by the database that do not match the original values assigned in the `DataRow`. By default, `AcceptChanges` is called implicitly after an update, and the original values in the row, which may have been values assigned by ADO.NET, are lost. You can preserve the original values in the `DataRow` by preventing `ADO.NET` from calling `AcceptChanges` after it performs an update on a row, by setting the property to `false`, which preserves the original values. + During a call to the `Update` method of a `DataAdapter`, the database can send data back to your ADO.NET application as output parameters or as the first returned record of a result set. ADO.NET can retrieve these values and update the corresponding columns in the being updated. By default, ADO.NET calls the `AcceptChanges` method of the `DataRow` after the update. However, if you want to merge the updated row back into another , you may want to preserver the original value of a primary key column. For example, a primary key column corresponding to an automatically incrementing column in the database, such as an identity column, can contain new values that are assigned by the database that do not match the original values assigned in the `DataRow`. By default, `AcceptChanges` is called implicitly after an update, and the original values in the row, which may have been values assigned by ADO.NET, are lost. You can preserve the original values in the `DataRow` by preventing `ADO.NET` from calling `AcceptChanges` after it performs an update on a row, by setting the property to `false`, which preserves the original values. > [!NOTE] -> Setting the `AcceptChangesDuringUpdate` property to `false` applies to all data modifications, not only inserts. If you want to edit or delete rows in the same update, and if you want to suppress the call to `AcceptChanges` only for inserts, then instead of setting `AcceptChangesDuringUpdate` to `false`, use an event handler for the `RowUpdated` event of the `DataAdapter`. In the event handler, you can check the to determine if the data modification is an insert, and if `true`, set the property of the to . For more information and an example, see [Retrieving Identity or Autonumber Values](/dotnet/framework/data/adonet/retrieving-identity-or-autonumber-values). +> Setting the `AcceptChangesDuringUpdate` property to `false` applies to all data modifications, not only inserts. If you want to edit or delete rows in the same update, and if you want to suppress the call to `AcceptChanges` only for inserts, then instead of setting `AcceptChangesDuringUpdate` to `false`, use an event handler for the `RowUpdated` event of the `DataAdapter`. In the event handler, you can check the to determine if the data modification is an insert, and if `true`, set the property of the to . For more information and an example, see [Retrieving Identity or Autonumber Values](/dotnet/framework/data/adonet/retrieving-identity-or-autonumber-values). @@ -393,9 +393,9 @@ constructor should be used instead of this method. + This method is deprecated. The constructor should be used instead of this method. - All the commands, the , the , and the are cloned. However, the connections for the commands are not copied, but shared. Thus, the cloned can be used against the same connection as the original. + All the commands, the , the , and the are cloned. However, the connections for the commands are not copied, but shared. Thus, the cloned can be used against the same connection as the original. ]]> @@ -639,20 +639,20 @@ method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). If the data adapter encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Applications using column and table names should ensure that conflicts with these naming patterns does not occur. When the SELECT statement used to populate the returns multiple results, such as a batch SQL statements, if one of the results contains an error, all subsequent results are skipped and not added to the . - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ]]> @@ -1020,23 +1020,23 @@ method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + The method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -1051,10 +1051,10 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Applications using column and table names should ensure that conflicts with these naming patterns does not occur. - does not return any rows. Use the method to add rows to a . + does not return any rows. Use the method to add rows to a . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ]]> @@ -1766,7 +1766,7 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1829,7 +1829,7 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta When reconciling changes, the uses the collection to associate the column names used by the data source with the column names used by the . ## Examples - The following example uses a derived class, , to add objects to its collection and display a list of those mapped source tables. This example assumes that an has already been created. + The following example uses a derived class, , to add objects to its collection and display a list of those mapped source tables. This example assumes that an has already been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataAdapter.TableMappings Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataAdapter/TableMappings/source.vb" id="Snippet1"::: @@ -1899,21 +1899,21 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta method determines the type of change that has been performed on it (Insert, Update or Delete). Depending on the type of change, the `Insert`, `Update,` or `Delete` command template executes to propagate the modified row to the data source. When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (Insert, Update or Delete). Depending on the type of change, the `Insert`, `Update,` or `Delete` command template executes to propagate the modified row to the data source. When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -1921,9 +1921,9 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. This will raise both the and events for the updated . +7. is called. This will raise both the and events for the updated . Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -1939,17 +1939,17 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta The `SourceVersion` property of a .NET data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - Calling the method or method will commit all changes in the or . If either of these methods are called before the method is called, no changes will be committed when the method is called, unless further changes have been made since or was called. + Calling the method or method will commit all changes in the or . If either of these methods are called before the method is called, no changes will be committed when the method is called, unless further changes have been made since or was called. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . > -> For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. +> For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. ## Examples - The following example uses the derived class, , to the data source. + The following example uses the derived class, , to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataAdapter.IDataAdapter.Update Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataAdapter/Update/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Common/DataColumnMapping.xml b/xml/System.Data.Common/DataColumnMapping.xml index 3107452d708..6c42393158f 100644 --- a/xml/System.Data.Common/DataColumnMapping.xml +++ b/xml/System.Data.Common/DataColumnMapping.xml @@ -67,19 +67,19 @@ Contains a generic column mapping for an object that inherits from . This class cannot be inherited. - enables you to use column names in a that are different from those in the data source. The `DataAdapter` uses the mapping to match the columns when the tables in the or data source are updated. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - - - -## Examples - The following example creates a object and adds it to a . It then tells the user that the mapping was added to the collection and shows the Parent for the mapping. - + enables you to use column names in a that are different from those in the data source. The `DataAdapter` uses the mapping to match the columns when the tables in the or data source are updated. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + + + +## Examples + The following example creates a object and adds it to a . It then tells the user that the mapping was added to the collection and shows the Parent for the mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -132,14 +132,14 @@ Initializes a new instance of the class. - object, sets its properties, and clones it. - + object, sets its properties, and clones it. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataColumnMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMapping/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMapping/.ctor/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -188,14 +188,14 @@ The column name, which is not case sensitive, from a to map to. Initializes a new instance of the class with the specified source column name and column name to map to. - object, sets its properties, and clones it. - + object, sets its properties, and clones it. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataColumnMapping1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMapping/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMapping/.ctor/source1.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -254,14 +254,14 @@ Gets or sets the name of the column within the to map to. The name of the column within the to map to. The name is not case sensitive. - object, and sets its properties. - + object, and sets its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -478,14 +478,14 @@ Gets or sets the name of the column within the data source to map from. The name is case-sensitive. The case-sensitive name of the column in the data source. - object, and sets its properties. - + object, and sets its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -535,13 +535,13 @@ Creates a new object that is a copy of the current instance. A copy of the current object. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -588,14 +588,14 @@ Converts the current name to a string. The current name as a string. - object and adds it to a collection. It then tells the user that the mapping was added to the collection and shows the parent of mapping. - + object and adds it to a collection. It then tells the user that the mapping was added to the collection and shows the parent of mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DataColumnMappingCollection.xml b/xml/System.Data.Common/DataColumnMappingCollection.xml index 4560b3f108e..b1080b824b2 100644 --- a/xml/System.Data.Common/DataColumnMappingCollection.xml +++ b/xml/System.Data.Common/DataColumnMappingCollection.xml @@ -69,14 +69,14 @@ Contains a collection of objects. - to several objects to its collection, and then displays a list of those mapped source columns. This example assumes that a has already been created. - + to several objects to its collection, and then displays a list of those mapped source columns. This example assumes that a has already been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -118,14 +118,14 @@ Creates an empty . - collection, adds objects to the collection, and displays a list of the mapped source columns. - + collection, adds objects to the collection, and displays a list of the mapped source columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.DataColumnMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/.ctor/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -190,14 +190,14 @@ Adds a object to the collection. The index of the object that was added to the collection. - object within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + object within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Add Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Add/source.vb" id="Snippet1"::: + ]]> The object passed in was not a object. @@ -257,14 +257,14 @@ Adds a object to the collection when given a source column name and a column name. The object that was added to the collection. - collection, adds objects to the collection, and displays a list of the mapped source columns. - + collection, adds objects to the collection, and displays a list of the mapped source columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.DataColumnMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/.ctor/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -415,14 +415,14 @@ Removes all objects from the collection. - objects. It then clears the collection, and returns `true` if the parameters are no longer persisting. This example assumes that a collection has been created. - + objects. It then clears the collection, and returns `true` if the parameters are no longer persisting. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Clear Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Clear/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Clear/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -488,14 +488,14 @@ if the collection contains the specified object; otherwise, . - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Contains1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Contains/source.vb" id="Snippet1"::: + ]]> The object passed in was not a object. @@ -551,14 +551,14 @@ if collection contains a object with the specified source column name; otherwise, . - object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -730,14 +730,14 @@ Gets the number of objects in the collection. The number of items in the collection. - collection, adds objects to the collection, and displays a list of the mapped source columns. - + collection, adds objects to the collection, and displays a list of the mapped source columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Count Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Count/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -787,14 +787,14 @@ Gets the object with the specified column name. The object with the specified column name. - within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.GetByDataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetByDataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetByDataSetColumn/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -862,27 +862,27 @@ Gets a for the specified , source column name, and . A object. - exists in the collection, it is returned. - - If the does not exist in the collection, for a given , the following actions occur: - -|MissingMappingAction|Action Taken| -|--------------------------|------------------| -|`Passthrough`|Creates a with the specified source column name as both the source column name and the column name. This is not added to the collection.| -|`Error`|An is generated if the specified column mapping is missing.| -|`Ignore`|Gets a null value.| - - - -## Examples - The following example searches for a with the given source column name within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + exists in the collection, it is returned. + + If the does not exist in the collection, for a given , the following actions occur: + +|MissingMappingAction|Action Taken| +|--------------------------|------------------| +|`Passthrough`|Creates a with the specified source column name as both the source column name and the column name. This is not added to the collection.| +|`Error`|An is generated if the specified column mapping is missing.| +|`Ignore`|Gets a null value.| + + + +## Examples + The following example searches for a with the given source column name within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.GetColumnMappingBySchemaAction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetColumnMappingBySchemaAction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetColumnMappingBySchemaAction/source.vb" id="Snippet1"::: + ]]> The parameter was set to , and no mapping was specified. @@ -1080,14 +1080,14 @@ Gets the location of the specified that is a within the collection. The zero-based location of the specified that is a within the collection. - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Contains1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Contains/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -1141,14 +1141,14 @@ Gets the location of the with the specified source column name. The zero-based location of the with the specified case-sensitive source column name. - object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -1199,14 +1199,14 @@ Gets the location of the specified with the given column name. The zero-based location of the specified with the given column name, or -1 if the object does not exist in the collection. - within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.GetByDataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetByDataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/GetByDataSetColumn/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -1391,14 +1391,14 @@ Gets or sets the object at the specified index. The object at the specified index. - collection, adds objects to the collection, and displays a list of the mapped source columns. - + collection, adds objects to the collection, and displays a list of the mapped source columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Count Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Count/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -1462,14 +1462,14 @@ Gets or sets the object with the specified source column name. The object with the specified source column name. - object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -1578,14 +1578,14 @@ The that is the to remove. Removes the that is a from the collection. - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.Add Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/Add/source.vb" id="Snippet1"::: + ]]> The object specified was not a object. @@ -1650,14 +1650,14 @@ The zero-based index of the object to remove. Removes the object with the specified index from the collection. - object with the given index within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. - + object with the given index within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.RemoveAt Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> There is no object with the specified index. @@ -1710,14 +1710,14 @@ The case-sensitive source column name. Removes the object with the specified source column name from the collection. - object with the given source column name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. - + object with the given source column name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.RemoveAt1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> There is no object with the specified source column name. @@ -1767,13 +1767,13 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -1821,13 +1821,13 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -1876,13 +1876,13 @@ if the has a fixed size; otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -1931,13 +1931,13 @@ if the is read-only; otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -1996,13 +1996,13 @@ Gets or sets the element at the specified index. The element at the specified index. - . - - This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - + . + + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. + ]]> ADO.NET Overview @@ -2057,13 +2057,13 @@ Adds a object to the by using the source column and column names. The ColumnMapping object that was added to the collection. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2116,13 +2116,13 @@ Gets the object that has the specified column name. The object that has the specified column name. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2174,13 +2174,13 @@ Gets or sets the object with the specified name. The object with the specified name. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DataTableMapping.xml b/xml/System.Data.Common/DataTableMapping.xml index c64da1c3766..3c333b3adfb 100644 --- a/xml/System.Data.Common/DataTableMapping.xml +++ b/xml/System.Data.Common/DataTableMapping.xml @@ -67,17 +67,17 @@ Contains a description of a mapped relationship between a source table and a . This class is used by a when populating a . - provides a primary mapping between the data returned from a query against a data source, and a . The name can be passed in place of the name to the `Fill` method of the **DataAdapter**. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - -## Examples - The following example creates a object and adds it to a . It then informs the user that the mapping was added to the collection and displays the parent mapping. - + provides a primary mapping between the data returned from a query against a data source, and a . The name can be passed in place of the name to the `Fill` method of the **DataAdapter**. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + +## Examples + The following example creates a object and adds it to a . It then informs the user that the mapping was added to the collection and displays the parent mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -130,14 +130,14 @@ Initializes a new instance of the class. - object. - + object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.DataTableMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/DataSetTable/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/DataSetTable/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -186,14 +186,14 @@ The table name from a to map to. Initializes a new instance of the class with a source when given a source table name and a name. - object and sets some of its properties. - + object and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.DataTableMapping1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source1.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -251,14 +251,14 @@ An array of objects. Initializes a new instance of the class when given a source table name, a name, and an array of objects. - object, sets some of its properties, and copies its to an array. This example assumes that a has been created. - + object, sets some of its properties, and copies its to an array. This example assumes that a has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.DataTableMapping2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source2.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -314,14 +314,14 @@ Gets the for the . A data column mapping collection. - object, sets some of its properties, and copies its to an array. This example assumes that a has been created. - + object, sets some of its properties, and copies its to an array. This example assumes that a has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.ColumnMappings Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/ColumnMappings/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/ColumnMappings/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -380,14 +380,14 @@ Gets or sets the table name from a . The table name from a . - object and sets some of its properties. - + object and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.DataSetTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -452,19 +452,19 @@ Gets a from the specified using the specified value and the name of the . A data column. - exists, it is returned. - - If the does not exist, for a given , the following actions occur: - -|MissingMappingAction|Action taken| -|--------------------------|------------------| -|`Passthrough`|Creates a with the specified source column name as both the source column name and the column name. This is not added to the collection.| -|`Error`|An is generated if the specified column mapping is missing.| -|`Ignore`|Gets a null value.| - + exists, it is returned. + + If the does not exist, for a given , the following actions occur: + +|MissingMappingAction|Action taken| +|--------------------------|------------------| +|`Passthrough`|Creates a with the specified source column name as both the source column name and the column name. This is not added to the collection.| +|`Error`|An is generated if the specified column mapping is missing.| +|`Ignore`|Gets a null value.| + ]]> The parameter was set to , and no mapping was specified. @@ -608,19 +608,19 @@ Gets the current for the specified using the specified value. A data table. - does not exist, the specified is taken. - - - -## Examples - The following example gets the for a given . If there is no current table for the , `null` is returned. This example assumes that a and a collection have been created. - + does not exist, the specified is taken. + + + +## Examples + The following example gets the for a given . If there is no current table for the , `null` is returned. This example assumes that a and a collection have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.GetDataTableBySchemaAction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/GetDataTableBySchemaAction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/GetDataTableBySchemaAction/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -679,14 +679,14 @@ Gets or sets the case-sensitive source table name from a data source. The case-sensitive source table name from a data source. - object and sets some of its properties. - + object and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.DataSetTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/.ctor/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -734,13 +734,13 @@ Gets the derived for the . A data column mapping collection. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -790,13 +790,13 @@ Creates a new object that is a copy of the current instance. A new object that is a copy of the current instance. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -843,14 +843,14 @@ Converts the current name to a string. The current name, as a string. - object and adds it to a collection. It then informs the user that the mapping has been added to the collection and displays the parent mapping. - + object and adds it to a collection. It then informs the user that the mapping has been added to the collection and displays the parent mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.ToString Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/ToString/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMapping/ToString/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DataTableMappingCollection.xml b/xml/System.Data.Common/DataTableMappingCollection.xml index d67d26d5a96..49463a298c8 100644 --- a/xml/System.Data.Common/DataTableMappingCollection.xml +++ b/xml/System.Data.Common/DataTableMappingCollection.xml @@ -85,14 +85,14 @@ A collection of objects. This class cannot be inherited. - to objects to its collection, and then displays a list of those mapped source tables. This example assumes that an has already been created. - + to objects to its collection, and then displays a list of those mapped source tables. This example assumes that an has already been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Overview/source.vb" id="Snippet1"::: + ]]> @@ -133,14 +133,14 @@ Initializes a new instance of the class. This new instance is empty, that is, it does not yet contain any objects. - , adds objects to the collection, and displays a list of the mapped source tables. - + , adds objects to the collection, and displays a list of the mapped source tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.DataTableMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -203,14 +203,14 @@ Adds an that is a table mapping to the collection. The index of the object added to the collection. - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Add Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Add/source.vb" id="Snippet1"::: + ]]> The object passed in was not a object. @@ -269,14 +269,14 @@ Adds a object to the collection when given a source table name and a table name. The object that was added to the collection. - , adds objects to the collection, and displays a list of the mapped source tables. - + , adds objects to the collection, and displays a list of the mapped source tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.DataTableMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -423,14 +423,14 @@ Removes all objects from the collection. - method to export the collection to an array of objects. It then clears the collection, and returns `true` if the parameters are no longer persisting. This example assumes that a has already been created. - + method to export the collection to an array of objects. It then clears the collection, and returns `true` if the parameters are no longer persisting. This example assumes that a has already been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Clear Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Clear/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Clear/source.vb" id="Snippet1"::: + ]]> @@ -494,14 +494,14 @@ if this collection contains the specified ; otherwise . - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Contains1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -555,14 +555,14 @@ if the collection contains a object with this source table name; otherwise . - object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: + ]]> @@ -730,14 +730,14 @@ Gets the number of objects in the collection. The number of objects in the collection. - , adds objects to the collection, and displays a list of the mapped source tables. - + , adds objects to the collection, and displays a list of the mapped source tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Count Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Count/source.vb" id="Snippet1"::: + ]]> @@ -786,14 +786,14 @@ Gets the object with the specified table name. The object with the specified table name. - within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.GetByDataSetTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetByDataSetTable/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetByDataSetTable/source.vb" id="Snippet1"::: + ]]> @@ -914,27 +914,27 @@ Gets a object with the specified source table name and table name, using the given . A object. - exists in the collection, it is returned. - - If the does not exist in the collection for a given , the following happens: - -|MissingMappingAction|Action taken| -|--------------------------|------------------| -|`Passthrough`|Creates a object with the given `sourceTable` as the source table name and `dataSetTable` as the table name. The created object is not added to the collection.| -|`Error`|An exception is generated. The `dataSetTable` parameter is ignored.| -|`Ignore`|Gets `null`. The `dataSetTable` parameter is ignored.| - - - -## Examples - The following example searches for a with the given source table name within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + exists in the collection, it is returned. + + If the does not exist in the collection for a given , the following happens: + +|MissingMappingAction|Action taken| +|--------------------------|------------------| +|`Passthrough`|Creates a object with the given `sourceTable` as the source table name and `dataSetTable` as the table name. The created object is not added to the collection.| +|`Error`|An exception is generated. The `dataSetTable` parameter is ignored.| +|`Ignore`|Gets `null`. The `dataSetTable` parameter is ignored.| + + + +## Examples + The following example searches for a with the given source table name within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.GetTableMappingBySchemaAction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetTableMappingBySchemaAction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetTableMappingBySchemaAction/source.vb" id="Snippet1"::: + ]]> The parameter was set to , and no mapping was specified. @@ -998,14 +998,14 @@ Gets the location of the specified object within the collection. The zero-based location of the specified object within the collection. - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Contains1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -1058,14 +1058,14 @@ Gets the location of the object with the specified source table name. The zero-based location of the object with the specified source table name. - object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: + ]]> @@ -1115,14 +1115,14 @@ Gets the location of the object with the specified table name. The zero-based location of the object with the given table name, or -1 if the object does not exist in the collection. - within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. - + within the collection. If the object exists, it is returned. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.GetByDataSetTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetByDataSetTable/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/GetByDataSetTable/source.vb" id="Snippet1"::: + ]]> @@ -1302,14 +1302,14 @@ Gets or sets the object at the specified index. The object at the specified index. - collection, adds objects to the collection, and displays a list of the mapped source tables. - + collection, adds objects to the collection, and displays a list of the mapped source tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Count Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Count/source.vb" id="Snippet1"::: + ]]> @@ -1372,14 +1372,14 @@ Gets or sets the object with the specified source table name. The object with the specified source table name. - object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + object with the given source table name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Contains/source1.vb" id="Snippet1"::: + ]]> @@ -1485,14 +1485,14 @@ The object to remove. Removes the specified object from the collection. - within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. - + within the collection. If the mapping exists in the collection, it is removed. If the mapping does not exist within the collection, it is added to the collection and its index is displayed. The example assumes that a collection and a object have been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.Add Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/Add/source.vb" id="Snippet1"::: + ]]> The object specified was not a object. @@ -1555,14 +1555,14 @@ The zero-based index of the object to remove. Removes the object located at the specified index from the collection. - object with the given source table name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. - + object with the given source table name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.RemoveAt Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> A object does not exist with the specified index. @@ -1614,14 +1614,14 @@ The case-sensitive source table name to find. Removes the object with the specified source table name from the collection. - object with the given source table name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. - + object with the given source table name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMappingCollection.RemoveAt1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/RemoveAt/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DataTableMappingCollection/RemoveAt/source1.vb" id="Snippet1"::: + ]]> A object does not exist with the specified source table name. @@ -1670,13 +1670,13 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -1723,13 +1723,13 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -1777,13 +1777,13 @@ if the has a fixed size; otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -1831,13 +1831,13 @@ if the is read-only; otherwise, . - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -1895,13 +1895,13 @@ Gets or sets an item from the collection at a specified index. The element at the specified index. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -1955,13 +1955,13 @@ Adds a table mapping to the collection. A reference to the newly-mapped object. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -2013,13 +2013,13 @@ Gets the TableMapping object with the specified table name. The TableMapping object with the specified table name. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> @@ -2070,13 +2070,13 @@ Gets or sets the instance of with the specified name. The instance of with the specified name. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> diff --git a/xml/System.Data.Common/DbBatch.xml b/xml/System.Data.Common/DbBatch.xml index 4e7ecdb3f26..982a04eb628 100644 --- a/xml/System.Data.Common/DbBatch.xml +++ b/xml/System.Data.Common/DbBatch.xml @@ -484,9 +484,9 @@ The precise semantics of batch execution vary across ADO.NET providers, especial to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. + You can use to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. - Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. + Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. @@ -605,7 +605,7 @@ The precise semantics of batch execution vary across ADO.NET providers, especial in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). ]]> @@ -646,7 +646,7 @@ The precise semantics of batch execution vary across ADO.NET providers, especial in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.Data.Common/DbCommand.xml b/xml/System.Data.Common/DbCommand.xml index 7324026bd38..f62a96bf102 100644 --- a/xml/System.Data.Common/DbCommand.xml +++ b/xml/System.Data.Common/DbCommand.xml @@ -999,9 +999,9 @@ to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. + You can use to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. - Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. + Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. @@ -1262,7 +1262,7 @@ in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). ]]> @@ -1315,7 +1315,7 @@ in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1375,7 +1375,7 @@ in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1435,7 +1435,7 @@ in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1496,7 +1496,7 @@ in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + Managed provider implementers must call in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1557,7 +1557,7 @@ method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method and performing the operations necessary to generate the single value using the data returned by a . + Use the method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method and performing the operations necessary to generate the single value using the data returned by a . If the first column of the first row in the result set is not found, a null reference (`Nothing` in Visual Basic) is returned. If the value in the database is `null`, the query returns `DBNull.Value`. @@ -1805,7 +1805,7 @@ property is set to `TableDirect`, `Prepare` does nothing. If is set to `StoredProcedure`, the call to `Prepare` should succeed, although it may result in a no-op. + If the property is set to `TableDirect`, `Prepare` does nothing. If is set to `StoredProcedure`, the call to `Prepare` should succeed, although it may result in a no-op. ]]> @@ -1856,7 +1856,7 @@ Data providers that support [asynchronous programming](/dotnet/framework/data/adonet/asynchronous-programming) should override the default implementation using asynchronous I/O operations. - If the property is set to `TableDirect`, `PrepareAsync` does nothing. If is set to `StoredProcedure`, the call to `PrepareAsync` should succeed, although it may result in a no-op. + If the property is set to `TableDirect`, `PrepareAsync` does nothing. If is set to `StoredProcedure`, the call to `PrepareAsync` should succeed, although it may result in a no-op. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1918,7 +1918,7 @@ . + For more information, see . ]]> @@ -1974,7 +1974,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2041,7 +2041,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2100,7 +2100,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2155,7 +2155,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DbCommandBuilder.xml b/xml/System.Data.Common/DbCommandBuilder.xml index 10df25ac81b..d6cf0fffe1c 100644 --- a/xml/System.Data.Common/DbCommandBuilder.xml +++ b/xml/System.Data.Common/DbCommandBuilder.xml @@ -60,13 +60,13 @@ The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved (for example, after the first update), you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved (for example, after the first update), you should call the method to update the metadata. The `SelectCommand` must also return at least one primary key or unique column. If none exist, an exception is generated, and the commands are not generated. - The also uses the , , and properties referenced by the . The user should call if any of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. + The also uses the , , and properties referenced by the . The user should call if any of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. - If you call , the is disassociated from the , and the generated commands are no longer used. + If you call , the is disassociated from the , and the generated commands are no longer used. ]]> @@ -433,9 +433,9 @@ method and the method, if it has been overridden. invokes the protected method with the disposing parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the disposing parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. -When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. +When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. ]]> @@ -461,13 +461,13 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the associated command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the associated command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . - The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior by supplying a Boolean value, you can cause the to generate parameters based on the column names instead by passing `True`. + The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior by supplying a Boolean value, you can cause the to generate parameters based on the column names instead by passing `True`. ]]> @@ -518,11 +518,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . ]]> @@ -576,11 +576,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -608,13 +608,13 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . - The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior, you can cause the to generate parameters based on the column names instead. + The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior, you can cause the to generate parameters based on the column names instead. ]]> @@ -665,11 +665,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . ]]> @@ -723,11 +723,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. Generation of the parameters based on column names succeeds only if the following conditions are met: @@ -975,13 +975,13 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . - The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior, you can cause the to generate parameters based on the column names instead. + The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. If the overloaded version of allows you to specify this behavior, you can cause the to generate parameters based on the column names instead. ]]> @@ -1032,11 +1032,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . ]]> @@ -1090,11 +1090,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify command text, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify command text, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. Generation of the parameters based on column names succeeds only if the following conditions are met: @@ -1267,10 +1267,10 @@ When the `disposing` parameter is `true`, this method releases all resources hel and properties to specify delimiters such as a left bracket and a right bracket to encapsulate the object name. + Some data sources may have objects that can contain characters such as spaces, commas, and semicolons. To accommodate this capability, use the and properties to specify delimiters such as a left bracket and a right bracket to encapsulate the object name. > [!NOTE] -> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a . +> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a . ]]> @@ -1327,10 +1327,10 @@ When the `disposing` parameter is `true`, this method releases all resources hel and properties to specify delimiters such as a left bracket and a right bracket to encapsulate the object name. + Some data sources may have objects that can contain characters such as spaces, commas, and semicolons. To accommodate this capability, use the and properties to specify delimiters such as a left bracket and a right bracket to encapsulate the object name. > [!NOTE] -> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a . +> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a . ]]> @@ -1380,13 +1380,13 @@ When the `disposing` parameter is `true`, this method releases all resources hel method effectively removes all the objects referred to by the , + Calling the method effectively removes all the objects referred to by the , - , + , - , and + , and - properties. + properties. ]]> diff --git a/xml/System.Data.Common/DbConnection.xml b/xml/System.Data.Common/DbConnection.xml index 3bce0de89ed..098140ed204 100644 --- a/xml/System.Data.Common/DbConnection.xml +++ b/xml/System.Data.Common/DbConnection.xml @@ -685,9 +685,9 @@ This property returns `false` by default; providers that implement and methods roll back any pending transactions. They then release the connection to the connection pool, or close the connection if connection pooling is disabled. + The and methods roll back any pending transactions. They then release the connection to the connection pool, or close the connection if connection pooling is disabled. - An application can call or more than one time. No exception is generated. + An application can call or more than one time. No exception is generated. If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling `Close` or `Dispose`, which are functionally equivalent. If the connection pooling value `Pooling` is set to `true` or `yes`, this also releases the physical connection. @@ -743,9 +743,9 @@ This property returns `false` by default; providers that implement and methods roll back any pending transactions. They then release the connection to the connection pool, or close the connection if connection pooling is disabled. + The and methods roll back any pending transactions. They then release the connection to the connection pool, or close the connection if connection pooling is disabled. - An application can call or more than one time. No exception is generated. + An application can call or more than one time. No exception is generated. If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling `Close` or `Dispose`, which are functionally equivalent. If the connection pooling value `Pooling` is set to `true` or `yes`, this also releases the physical connection. @@ -1135,7 +1135,7 @@ This property returns `false` by default; providers that implement returns whatever is contained in the for the `DataSource` keyword. If the connection is open and the data source keyword's value starts with "|`datadirectory`|", the property returns whatever is contained in the for the `DataSource` keyword only. If the connection to the database is open, the property returns what the native provider returns for the `DBPROP_INIT_DATASOURCE`, and if that is empty, the native provider's `DBPROP_DATASOURCENAME` is returned. + If the connection to the database is closed, the returns whatever is contained in the for the `DataSource` keyword. If the connection is open and the data source keyword's value starts with "|`datadirectory`|", the property returns whatever is contained in the for the `DataSource` keyword only. If the connection to the database is open, the property returns what the native provider returns for the `DBPROP_INIT_DATASOURCE`, and if that is empty, the native provider's `DBPROP_DATASOURCENAME` is returned. ]]> @@ -1785,7 +1785,7 @@ This property returns `false` by default; providers that implement will throw an exception if called again without first being closed. + This method must be overridden with user-defined behavior. will throw an exception if called again without first being closed. ]]> @@ -1855,9 +1855,9 @@ This property returns `false` by default; providers that implement , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . + After calling , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . - A call to will attempt to cancel or close the corresponding call. + A call to will attempt to cancel or close the corresponding call. For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). @@ -1919,9 +1919,9 @@ This property returns `false` by default; providers that implement , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . + After calling , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . - A call to will attempt to cancel or close the corresponding call. + A call to will attempt to cancel or close the corresponding call. For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). @@ -2155,7 +2155,7 @@ This property returns `false` by default; providers that implement instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2212,7 +2212,7 @@ This property returns `false` by default; providers that implement . + For more information, see . ]]> @@ -2266,7 +2266,7 @@ This property returns `false` by default; providers that implement . + For more information, see [Commands and Parameters](/dotnet/framework/data/adonet/commands-and-parameters) and . ]]> diff --git a/xml/System.Data.Common/DbConnectionStringBuilder.xml b/xml/System.Data.Common/DbConnectionStringBuilder.xml index 0300d49fdaa..97b120732ff 100644 --- a/xml/System.Data.Common/DbConnectionStringBuilder.xml +++ b/xml/System.Data.Common/DbConnectionStringBuilder.xml @@ -95,7 +95,7 @@ If you need to create connection strings as part of applications, use the class. The performs no checks for valid key/value pairs. Therefore, it's possible to create invalid connection strings when using this class. The supports only key/value pairs that are supported by SQL Server; trying to add invalid pairs will throw an exception. - Both the method and property handle cases where a bad actor tries to insert malicious entries. For example, the following code correctly escapes the nested key/value pair: + Both the method and property handle cases where a bad actor tries to insert malicious entries. For example, the following code correctly escapes the nested key/value pair: ```vb Dim builder As New System.Data.Common.DbConnectionStringBuilder @@ -285,7 +285,7 @@ initial catalog="AdventureWorks;NewValue=Bad" ## Remarks The property can also be used to add new elements by setting the value of a key that does not exist in the dictionary. For example: `myCollection["myNonexistentKey"] = myValue`. - Calling the method by passing a null (`Nothing` in Visual Basic) key throws an . However, calling the method by passing a null value removes the key/value pair. + Calling the method by passing a null (`Nothing` in Visual Basic) key throws an . However, calling the method by passing a null value removes the key/value pair. ]]> @@ -581,7 +581,7 @@ initial catalog="AdventureWorks;NewValue=Bad" method removes all key/value pairs from the and resets all corresponding properties. This includes setting the property to 0 and the property to an empty string. + The method removes all key/value pairs from the and resets all corresponding properties. This includes setting the property to 0 and the property to an empty string. ]]> @@ -910,7 +910,7 @@ The collection contains the key "Data Source". ## Remarks Comparisons on key names are case insensitive; value comparisons are case sensitive. - The method returns `true` if the key/value pairs are equal, regardless of their order. The connection behavior of the two connection strings are equivalent, because order is never significant within connection strings. However, different order may affect connection pooling behavior of connections based on these connection strings. + The method returns `true` if the key/value pairs are equal, regardless of their order. The connection behavior of the two connection strings are equivalent, because order is never significant within connection strings. However, different order may affect connection pooling behavior of connections based on these connection strings. @@ -1311,7 +1311,7 @@ builder2.EquivalentTo(builder3) = False method returns a value that indicates its success, it is not required to look for the key before trying to remove the key/value pair from the instance. + Because the method returns a value that indicates its success, it is not required to look for the key before trying to remove the key/value pair from the instance. @@ -1388,7 +1388,7 @@ jet oledb:system database=system.mdw method. + This method behaves identically to the method. ]]> @@ -1450,7 +1450,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -1507,7 +1507,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1563,7 +1563,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1624,7 +1624,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -1685,7 +1685,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1742,7 +1742,7 @@ jet oledb:system database=system.mdw ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -1883,7 +1883,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1942,7 +1942,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -1999,7 +1999,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2054,7 +2054,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2109,7 +2109,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2164,7 +2164,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2225,7 +2225,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2286,7 +2286,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2347,7 +2347,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -2415,7 +2415,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2480,7 +2480,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2544,7 +2544,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2615,7 +2615,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2679,7 +2679,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2737,7 +2737,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2853,12 +2853,12 @@ This member is an explicit interface member implementation. It can be used only method lets developers safely retrieve a value from a without needing to first call the method. Because does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key will place the null value (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from a without needing to first call the method. Because does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key will place the null value (`Nothing` in Visual Basic) in the `value` parameter. ## Examples - The following example calls the method, demonstrating several possible outcomes. + The following example calls the method, demonstrating several possible outcomes. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DbConnectionStringBuilder.TryGetValue/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbConnectionStringBuilder/TryGetValue/source.vb" id="Snippet1"::: @@ -2933,7 +2933,7 @@ Unable to retrieve value for null key. is unspecified, but it is the same order as the associated keys in the returned by the method. + The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the method. The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the are reflected in the . diff --git a/xml/System.Data.Common/DbDataAdapter.xml b/xml/System.Data.Common/DbDataAdapter.xml index f4418e56ad8..1422b4a59a5 100644 --- a/xml/System.Data.Common/DbDataAdapter.xml +++ b/xml/System.Data.Common/DbDataAdapter.xml @@ -75,7 +75,7 @@ An application does not create an instance of the class directly, but creates an instance of a class that inherits from it. - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the class defines the property, and the class defines eight overloads of the method. In turn, the class inherits the method, and also defines two additional overloads of that take an ADO Recordset object as a parameter. + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the class defines the property, and the class defines eight overloads of the method. In turn, the class inherits the method, and also defines two additional overloads of that take an ADO Recordset object as a parameter. ]]> @@ -164,12 +164,12 @@ |Properties|Initial value| |----------------|-------------------| -||A new .| -||A new .| -||A new .| -||A new .| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||A new .| +||A new .| +||A new .| +||A new .| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -527,7 +527,7 @@ ## Remarks "Table" is the default name used by the object for table mappings. - is when an application adds a table mapping to be used with , but does not specify a name. + is when an application adds a table mapping to be used with , but does not specify a name. ]]> @@ -592,7 +592,7 @@ , if this property is not set and primary key information is present in the , the is automatically generated. + During , if this property is not set and primary key information is present in the , the is automatically generated. @@ -775,7 +775,7 @@ method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + The method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. @@ -787,18 +787,18 @@ When the SELECT statement used to populate the returns multiple results, such as batch SQL statements, if one of the results contains an error, all subsequent results are skipped and are not added to the . - When using subsequent calls to refresh the contents of the , two conditions must be met: + When using subsequent calls to refresh the contents of the , two conditions must be met: 1. The SQL statement should match the one initially used to populate the . 2. The **Key** column information must be present. - If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ]]> @@ -853,15 +853,15 @@ method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. - The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. + The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -871,7 +871,7 @@ DataSet dataset = new DataSet(); adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -879,12 +879,12 @@ DataSet dataset = new DataSet(); adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. ``` - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. +> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. ]]> @@ -945,7 +945,7 @@ DataSet dataset = new DataSet(); method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. If a command does not return any rows, no tables are added to the , and no exception is raised. @@ -953,7 +953,7 @@ DataSet dataset = new DataSet(); When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -963,7 +963,7 @@ adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSe adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -977,16 +977,16 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na - If one of the results contains an error, all subsequent results are skipped and not added to the . - When using subsequent calls to refresh the contents of the , two conditions must be met: + When using subsequent calls to refresh the contents of the , two conditions must be met: 1. The SQL statement should match the one initially used to populate the . -2. The **Key** column information must be present. If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. +2. The **Key** column information must be present. If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ## Examples The following example uses the derived class, , to fill a with rows from the categories table. This example assumes that you have created an and a . @@ -1088,20 +1088,20 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to the specified destination object in the , creating the object if it does not already exist. When creating a object, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to the specified destination object in the , creating the object if it does not already exist. When creating a object, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. + The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ]]> @@ -1172,20 +1172,20 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na A `maxRecords` value of 0 gets all records found after the start record. If `maxRecords` is greater than the number of remaining rows, only the remaining rows are returned, and no error is issued. - The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, and then it is closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, and then it is closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). If the data adapter encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the , each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. When the SELECT statement used to populate the returns multiple results, such as a batch SQL statements, if one of the results contains an error, all subsequent results are skipped and not added to the . - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. ]]> @@ -1257,9 +1257,9 @@ A `maxRecords` value of 0 gets all records found after the start record. If `max A `maxRecords` value of 0 gets all records found after the start record. If `maxRecords` is greater than the number of remaining rows, only the remaining rows are returned, and no error is issued. - If the corresponding select command is a statement returning multiple results, only applies `maxRecords` to the first result. + If the corresponding select command is a statement returning multiple results, only applies `maxRecords` to the first result. - The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. If a command does not return any rows, no tables are added to the , but no exception is raised. @@ -1267,7 +1267,7 @@ A `maxRecords` value of 0 gets all records found after the start record. If `max When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Because no table is created for a query that does not return rows, if you process an insert query followed by a select query, the table created for the select query is named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1277,7 +1277,7 @@ adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSe adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1293,18 +1293,18 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na - If one of the results contains an error, all subsequent results are skipped and not added to the . - When using subsequent calls to refresh the contents of the , two conditions must be met: + When using subsequent calls to refresh the contents of the , two conditions must be met: 1. The SQL statement should match the one initially used to populate the . 2. The **Key** column information must be present. - If primary key information is present, any duplicate rows will be reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + If primary key information is present, any duplicate rows will be reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. > [!NOTE] > The `DataSet` will not contain more than the number of records indicated by `maxRecords`. However, the entire result set generated by the query is still returned from the server. @@ -1438,7 +1438,7 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na A `maxRecords` value of 0 gets all records found after the start record. If `maxRecords` is greater than the number of remaining rows, only the remaining rows are returned and no error is issued. - The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. If a command does not return any rows, no tables are added to the , but no exception is raised. @@ -1446,7 +1446,7 @@ A `maxRecords` value of 0 gets all records found after the start record. If `max When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1456,7 +1456,7 @@ adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSe adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1556,13 +1556,13 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na A `maxRecords` value of 0 gets all records found after the start record. If `maxRecords` is greater than the number of remaining rows, only the remaining rows are returned and no error is issued. - The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1572,7 +1572,7 @@ adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSe adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -1580,12 +1580,12 @@ dataset.Tables.Add("aaa"); adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. ``` - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. +> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. ]]> @@ -1746,23 +1746,23 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na . + This method retrieves the schema information from the data source using the . - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -1772,16 +1772,16 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. + Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. + The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). @@ -1859,25 +1859,25 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - A operation returns a . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation returns a . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If a has already been defined for the `DataTable`, or the `DataTable` contains data, the `PrimaryKey` property will not be set. +- If a has already been defined for the `DataTable`, or the `DataTable` contains data, the `PrimaryKey` property will not be set. -- If one or more primary key columns are returned by the , they are used as the primary key columns for the `DataTable`. +- If one or more primary key columns are returned by the , they are used as the primary key columns for the `DataTable`. - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the `PrimaryKey` property is not set. @@ -1889,12 +1889,12 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - does not return any rows. Use the method to add rows to a . + does not return any rows. Use the method to add rows to a . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). @@ -1967,23 +1967,23 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na . + This method retrieves the schema information from the data source using the . - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -1993,11 +1993,11 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. + Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -2007,7 +2007,7 @@ adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -2015,12 +2015,12 @@ dataset.Tables.Add("aaa"); adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. ``` - The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. + The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). @@ -2103,23 +2103,23 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -2131,12 +2131,12 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - does not return any rows. Use the method to add rows to a . + does not return any rows. Use the method to add rows to a . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). ]]> @@ -2208,23 +2208,23 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -2236,7 +2236,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -2246,7 +2246,7 @@ adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -2254,12 +2254,12 @@ dataset.Tables.Add("aaa"); adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. ``` - does not return any rows. Use the method to add rows to a . + does not return any rows. Use the method to add rows to a . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. The user should be aware of potential side effects, such as interference with the use of SET FMTONLY ON statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). ]]> @@ -2556,7 +2556,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o , if this property is not set and primary key information is present in the , the will be automatically generated. + During , if this property is not set and primary key information is present in the , the will be automatically generated. @@ -2848,7 +2848,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2909,7 +2909,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -2970,7 +2970,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -3031,7 +3031,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -3093,7 +3093,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -3220,21 +3220,21 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -3242,9 +3242,9 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -3261,7 +3261,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . @@ -3346,21 +3346,21 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -3368,9 +3368,9 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -3387,7 +3387,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . @@ -3459,21 +3459,21 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -3481,9 +3481,9 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -3500,7 +3500,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . @@ -3584,21 +3584,21 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -3606,9 +3606,9 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -3625,7 +3625,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . ]]> @@ -3701,13 +3701,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method supports scenarios where the contains multiple objects whose names differ only by case. When multiple tables with the same name, but different case, exist in a `DataSet`, performs a case-sensitive comparison to find the corresponding table, and generates an exception if no exact match exists. The following C# code illustrates this behavior. + The method supports scenarios where the contains multiple objects whose names differ only by case. When multiple tables with the same name, but different case, exist in a `DataSet`, performs a case-sensitive comparison to find the corresponding table, and generates an exception if no exact match exists. The following C# code illustrates this behavior. ``` DataSet ds = new DataSet(); @@ -3718,7 +3718,7 @@ DataSet ds = new DataSet(); adapter.Update(ds, "Aaa"); // Results in an exception. ``` - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. ``` DataSet dataset = new DataSet(); @@ -3726,15 +3726,15 @@ DataSet dataset = new DataSet(); adapter.Update(dataset, "AAA"); // Updates table "aaa" because only one similarly named table is in the DataSet. ``` - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -3742,9 +3742,9 @@ DataSet dataset = new DataSet(); 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -3761,7 +3761,7 @@ DataSet dataset = new DataSet(); The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . @@ -3919,7 +3919,7 @@ DataSet dataset = new DataSet(); , if this property is not set and primary key information is present in the , the will be automatically generated. + During , if this property is not set and primary key information is present in the , the will be automatically generated. diff --git a/xml/System.Data.Common/DbDataReader.xml b/xml/System.Data.Common/DbDataReader.xml index 4719c114c73..608e364bd35 100644 --- a/xml/System.Data.Common/DbDataReader.xml +++ b/xml/System.Data.Common/DbDataReader.xml @@ -412,7 +412,7 @@ . + This method calls . ]]> @@ -524,7 +524,7 @@ to exclude hidden fields. + Includes hidden fields. Use to exclude hidden fields. ]]> @@ -2083,7 +2083,7 @@ private static void GetCredits(String connectionString) . + To determine the specific type of the object returned, use . ]]> @@ -2291,7 +2291,7 @@ Returns if the executed command returned no resultset, o only supports the retrieval of values that can be converted to byte arrays. + only supports the retrieval of values that can be converted to byte arrays. ]]> The connection was dropped or closed during the data retrieval. @@ -2415,7 +2415,7 @@ Returns if the executed command returned no resultset, o only supports the retrieval of values that can be converted to character arrays (strings). + only supports the retrieval of values that can be converted to character arrays (strings). ]]> The connection was dropped or closed during the data retrieval. @@ -2691,7 +2691,7 @@ Returns if the executed command returned no resultset, o , , and so on) to avoid throwing an exception. + Call this method to check for null column values before calling the typed Get_*_ methods (for example, , , and so on) to avoid throwing an exception. ]]> @@ -3229,7 +3229,7 @@ Returns if the executed command returned no resultset, o to begin accessing data. + The default position of a data reader is before the first record. Therefore, you must call to begin accessing data. ]]> diff --git a/xml/System.Data.Common/DbDataRecord.xml b/xml/System.Data.Common/DbDataRecord.xml index 7be1f92ae12..f43ad1afd3e 100644 --- a/xml/System.Data.Common/DbDataRecord.xml +++ b/xml/System.Data.Common/DbDataRecord.xml @@ -216,11 +216,11 @@ if the Boolean is ; otherwise . - ADO.NET Overview @@ -278,11 +278,11 @@ Returns the value of the specified column as a byte. The value of the specified column. - ADO.NET Overview @@ -349,11 +349,11 @@ Returns the value of the specified column as a byte array. The value of the specified column. - ADO.NET Overview @@ -411,11 +411,11 @@ Returns the value of the specified column as a character. The value of the specified column. - ADO.NET Overview @@ -482,11 +482,11 @@ Returns the value of the specified column as a character array. The value of the specified column. - ADO.NET Overview @@ -650,11 +650,11 @@ Returns the value of the specified column as a object. The value of the specified column. - object. - + object. + ]]> ADO.NET Overview @@ -759,11 +759,11 @@ Returns the value of the specified column as a object. The value of the specified column. - object. - + object. + ]]> ADO.NET Overview @@ -821,11 +821,11 @@ Returns the value of the specified column as a double-precision floating-point number. The value of the specified column. - ADO.NET Overview @@ -944,11 +944,11 @@ Returns the value of the specified column as a single-precision floating-point number. The value of the specified column. - ADO.NET Overview @@ -1062,11 +1062,11 @@ Returns the value of the specified column as a 16-bit signed integer. The value of the specified column. - ADO.NET Overview @@ -1124,11 +1124,11 @@ Returns the value of the specified column as a 32-bit signed integer. The value of the specified column. - ADO.NET Overview @@ -1186,11 +1186,11 @@ Returns the value of the specified column as a 64-bit signed integer. The value of the specified column. - ADO.NET Overview @@ -1358,11 +1358,11 @@ Returns the value of the specified column as a string. The value of the specified column. - ADO.NET Overview @@ -1475,11 +1475,11 @@ Populates an array of objects with the column values of the current record. The number of instances of in the array. - ADO.NET Overview @@ -1538,11 +1538,11 @@ if the specified column is equivalent to ; otherwise . - , , and so on) to avoid raising an error. - + , , and so on) to avoid raising an error. + ]]> ADO.NET Overview @@ -1711,11 +1711,11 @@ Returns a collection of custom attributes for this instance of a component. An that contains the attributes for this object. - . - + . + ]]> ADO.NET Overview @@ -1765,11 +1765,11 @@ Returns the class name of this instance of a component. The class name of the object, or if the class does not have a name. - . - + . + ]]> ADO.NET Overview @@ -1819,11 +1819,11 @@ Returns the name of this instance of a component. The name of the object, or if the object does not have a name. - . - + . + ]]> ADO.NET Overview @@ -1879,11 +1879,11 @@ Returns a type converter for this instance of a component. A that is the converter for this object, or if there is no for this object. - . - + . + ]]> ADO.NET Overview @@ -1939,11 +1939,11 @@ Returns the default event for this instance of a component. An that represents the default event for this object, or if this object does not have events. - . - + . + ]]> ADO.NET Overview @@ -1999,11 +1999,11 @@ Returns the default property for this instance of a component. A that represents the default property for this object, or if this object does not have properties. - . - + . + ]]> ADO.NET Overview @@ -2066,11 +2066,11 @@ Returns an editor of the specified type for this instance of a component. An of the specified type that is the editor for this object, or if the editor cannot be found. - . - + . + ]]> ADO.NET Overview @@ -2120,11 +2120,11 @@ Returns the events for this instance of a component. An that represents the events for this component instance. - . - + . + ]]> ADO.NET Overview @@ -2183,11 +2183,11 @@ Returns the events for this instance of a component using the specified attribute array as a filter. An that represents the filtered events for this component instance. - . - + . + ]]> ADO.NET Overview @@ -2243,11 +2243,11 @@ Returns the properties for this instance of a component. A that represents the properties for this component instance. - . - + . + ]]> ADO.NET Overview @@ -2306,11 +2306,11 @@ Returns the properties for this instance of a component using the attribute array as a filter. A that represents the filtered properties for this component instance. - . - + . + ]]> ADO.NET Overview @@ -2363,11 +2363,11 @@ Returns an object that contains the property described by the specified property descriptor. An that represents the owner of the specified property. - . - + . + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DbDataSource.xml b/xml/System.Data.Common/DbDataSource.xml index eb72c8c5b5d..8ba244ac62d 100644 --- a/xml/System.Data.Common/DbDataSource.xml +++ b/xml/System.Data.Common/DbDataSource.xml @@ -108,9 +108,9 @@ ; their does not need to be set, and doing so will throw an exception. + Batches returned from this method are already configured to execute against their originating ; their does not need to be set, and doing so will throw an exception. - Since these batches have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. + Since these batches have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. ]]> @@ -152,9 +152,9 @@ ; their does not need to be set, and doing so will throw an exception. + Commands returned from this method are already configured to execute against their originating ; their does not need to be set, and doing so will throw an exception. - Since these commands have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. + Since these commands have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. ]]> diff --git a/xml/System.Data.Common/DbEnumerator.xml b/xml/System.Data.Common/DbEnumerator.xml index 2ec5ea0d66b..30f2c8c9e74 100644 --- a/xml/System.Data.Common/DbEnumerator.xml +++ b/xml/System.Data.Common/DbEnumerator.xml @@ -57,13 +57,13 @@ Exposes the method, which supports a simple iteration over a collection by a .NET data provider. - class is implemented by a .NET Framework data provider to provide data binding support. - - By design, the object is intended for use with only one resultset. For example, if you execute a batch statement containing two SQL SELECT statements that return different schemas, the second statement might not retun the entire schema. To avoid this situation, obtain a for each resultset, and then call the `NextResult` method of a .NET Framework data provider DataReader object. - + class is implemented by a .NET Framework data provider to provide data binding support. + + By design, the object is intended for use with only one resultset. For example, if you execute a batch statement containing two SQL SELECT statements that return different schemas, the second statement might not retun the entire schema. To avoid this situation, obtain a for each resultset, and then call the `NextResult` method of a .NET Framework data provider DataReader object. + ]]> ADO.NET Overview @@ -297,11 +297,11 @@ Gets the current element in the collection. The current element in the collection. - , must be called to advance the enumerator to the first element of the collection before reading the value of ; otherwise, is undefined. also throws an exception if the last call to returned false, which indicates the end of the collection. does not move the position of the enumerator and consecutive calls to return the same object until either or is called. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to or generates an . If the collection is modified between and , returns the element to which it is set, even if the enumerator is already invalidated. - + , must be called to advance the enumerator to the first element of the collection before reading the value of ; otherwise, is undefined. also throws an exception if the last call to returned false, which indicates the end of the collection. does not move the position of the enumerator and consecutive calls to return the same object until either or is called. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to or generates an . If the collection is modified between and , returns the element to which it is set, even if the enumerator is already invalidated. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -354,11 +354,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - , an enumerator is positioned before the first element of the collection, and the first call to moves the enumerator over the first element of the collection. After the end of the collection is passed, subsequent calls to return false until is called. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + , an enumerator is positioned before the first element of the collection, and the first call to moves the enumerator over the first element of the collection. After the end of the collection is passed, subsequent calls to return false until is called. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -415,11 +415,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Data.Common/DbParameter.xml b/xml/System.Data.Common/DbParameter.xml index 9db12d34045..cf712a10acd 100644 --- a/xml/System.Data.Common/DbParameter.xml +++ b/xml/System.Data.Common/DbParameter.xml @@ -238,7 +238,7 @@ ## Remarks If the is output, and execution of the associated does not return a value, the contains a null value. - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or on the . + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or on the . ]]> @@ -548,19 +548,19 @@ ## Remarks The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. - For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. + For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. - For bidirectional and output parameters, and return values, you must set the value of . This is not required for input parameters, and if not explicitly set, the value is inferred from the actual size of the specified parameter when a parameterized statement is executed. + For bidirectional and output parameters, and return values, you must set the value of . This is not required for input parameters, and if not explicitly set, the value is inferred from the actual size of the specified parameter when a parameterized statement is executed. - The and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. + The and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. - For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. + For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. - If the size of the value supplied for a exceeds the specified , the of the will contain the specified value, truncated to the Size of the . + If the size of the value supplied for a exceeds the specified , the of the will contain the specified value, truncated to the Size of the . - For parameters of type `DbType`.`String`, the value of is length in Unicode characters. For parameters of type `DbType`.`Xml`, is ignored. + For parameters of type `DbType`.`String`, the value of is length in Unicode characters. For parameters of type `DbType`.`Xml`, is ignored. ]]> @@ -620,7 +620,7 @@ is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. + When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -688,16 +688,16 @@ is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When generates its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When generates its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): ```tsql ((@IsNull_FieldName = 1 AND FieldName IS NULL) OR (FieldName = @Original_FieldName)) ``` - If for the field is `false`, generates the following WHERE clause: + If for the field is `false`, generates the following WHERE clause: ```tsql FieldName = @OriginalFieldName @@ -764,7 +764,7 @@ FieldName = @OriginalFieldName during an operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the `DataRow.Item` property, or the method of the object. + Used by during an operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the `DataRow.Item` property, or the method of the object. ]]> @@ -859,7 +859,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -914,7 +914,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DbParameterCollection.xml b/xml/System.Data.Common/DbParameterCollection.xml index 085988e395f..effe959661f 100644 --- a/xml/System.Data.Common/DbParameterCollection.xml +++ b/xml/System.Data.Common/DbParameterCollection.xml @@ -1806,7 +1806,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> @@ -1910,7 +1910,7 @@ This member is an explicit interface member implementation. ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DbProviderFactories.xml b/xml/System.Data.Common/DbProviderFactories.xml index 1393361d1a9..e92871fe366 100644 --- a/xml/System.Data.Common/DbProviderFactories.xml +++ b/xml/System.Data.Common/DbProviderFactories.xml @@ -158,11 +158,11 @@ Returns an instance of a . An instance of a for a specified . - of a table returned by . - + of a table returned by . + ]]> DbProviderFactories (ADO.NET) @@ -209,13 +209,13 @@ Returns an instance of a . An instance of a for a specified provider name. - . + . If you pass a value for `providerInvariantName` that's not valid, an exception is raised with the message, "Unable to find the requested .NET Framework Data Provider. It may not be installed." - + ]]> DbProviderFactories (ADO.NET) @@ -257,38 +257,38 @@ Returns a that contains information about all installed providers that implement . - A containing objects that contain the following data: - - Column ordinal - - Column name - - Description - - 0 - - **Name** - - Human-readable name for the data provider. - - 1 - - **Description** - - Human-readable description of the data provider. - - 2 - - **InvariantName** - - Name that can be used programmatically to refer to the data provider. - - 3 - - **AssemblyQualifiedName** - - Fully qualified name of the factory class, which contains enough information to instantiate the object. - + A containing objects that contain the following data: + + Column ordinal + + Column name + + Description + + 0 + + **Name** + + Human-readable name for the data provider. + + 1 + + **Description** + + Human-readable description of the data provider. + + 2 + + **InvariantName** + + Name that can be used programmatically to refer to the data provider. + + 3 + + **AssemblyQualifiedName** + + Fully qualified name of the factory class, which contains enough information to instantiate the object. + To be added. DbProviderFactories (ADO.NET) diff --git a/xml/System.Data.Common/DbTransaction.xml b/xml/System.Data.Common/DbTransaction.xml index afbd6ce8601..87fd125c78f 100644 --- a/xml/System.Data.Common/DbTransaction.xml +++ b/xml/System.Data.Common/DbTransaction.xml @@ -214,11 +214,11 @@ Asynchronously commits the database transaction. A representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -276,11 +276,11 @@ Specifies the object associated with the transaction. The object associated with the transaction. - Transactions and Concurrency (ADO.NET) @@ -335,11 +335,11 @@ When overridden in a derived class, gets the object associated with the transaction. The object associated with the transaction. - Transactions and Concurrency (ADO.NET) @@ -354,11 +354,11 @@ Releases the unmanaged resources used by the and optionally releases the managed resources. - should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . - + should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . + ]]> Transactions and Concurrency (ADO.NET) @@ -409,11 +409,11 @@ Releases the unmanaged resources used by the . - should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . - + should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . + ]]> Transactions and Concurrency (ADO.NET) @@ -464,11 +464,11 @@ If , this method releases all resources held by any managed objects that this references. Releases the unmanaged resources used by the and optionally releases the managed resources. - should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . - + should rollback the transaction. However, the behavior of is provider specific, and should not replace calling . + ]]> Transactions and Concurrency (ADO.NET) @@ -513,13 +513,13 @@ Asynchronously disposes the transaction object. A representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -761,13 +761,13 @@ Asynchronously rolls back a transaction from a pending state. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> diff --git a/xml/System.Data.Common/RowUpdatedEventArgs.xml b/xml/System.Data.Common/RowUpdatedEventArgs.xml index 98a1334521c..18cc6889f5a 100644 --- a/xml/System.Data.Common/RowUpdatedEventArgs.xml +++ b/xml/System.Data.Common/RowUpdatedEventArgs.xml @@ -59,7 +59,7 @@ to a row is completed. + The `RowUpdated` event message is typically raised when an to a row is completed. ]]> @@ -244,7 +244,7 @@ in length. + `array` must be at least in length. Throws an for a null instance of . @@ -301,7 +301,7 @@ + `arrayIndex` in length. + `array` must be at least + `arrayIndex` in length. Throws an for a null instance of . @@ -544,7 +544,7 @@ can be one of the following values: + can be one of the following values: - Select diff --git a/xml/System.Data.Common/RowUpdatingEventArgs.xml b/xml/System.Data.Common/RowUpdatingEventArgs.xml index 2b3f9504278..5f9eadaf463 100644 --- a/xml/System.Data.Common/RowUpdatingEventArgs.xml +++ b/xml/System.Data.Common/RowUpdatingEventArgs.xml @@ -59,7 +59,7 @@ to a row begins. + The `RowUpdating` event is typically raised just before an to a row begins. ]]> @@ -359,7 +359,7 @@ can be one of the following values: + can be one of the following values: - Select diff --git a/xml/System.Data.Design/TypedDataSetGeneratorException.xml b/xml/System.Data.Design/TypedDataSetGeneratorException.xml index d0c162ed95f..d3a535caa6d 100644 --- a/xml/System.Data.Design/TypedDataSetGeneratorException.xml +++ b/xml/System.Data.Design/TypedDataSetGeneratorException.xml @@ -74,8 +74,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. @@ -139,8 +139,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. @@ -210,8 +210,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. diff --git a/xml/System.Data.Entity.Design.AspNet/EntityModelBuildProvider.xml b/xml/System.Data.Entity.Design.AspNet/EntityModelBuildProvider.xml index 876ec88fe4f..cc08c940025 100644 --- a/xml/System.Data.Entity.Design.AspNet/EntityModelBuildProvider.xml +++ b/xml/System.Data.Entity.Design.AspNet/EntityModelBuildProvider.xml @@ -72,11 +72,11 @@ The assembly builder that references the source code generated by the build provider. Generates source code for the entity model build provider, and adds the source code to a specified assembly builder. - method embeds the CSDL file as a resource in the dynamically compiled assembly and also generates classes from CSDL file. - + method embeds the CSDL file as a resource in the dynamically compiled assembly and also generates classes from CSDL file. + ]]> diff --git a/xml/System.Data.Entity.Design.PluralizationServices/PluralizationService.xml b/xml/System.Data.Entity.Design.PluralizationServices/PluralizationService.xml index ece0de7bf0a..031796adf43 100644 --- a/xml/System.Data.Entity.Design.PluralizationServices/PluralizationService.xml +++ b/xml/System.Data.Entity.Design.PluralizationServices/PluralizationService.xml @@ -16,11 +16,11 @@ Provides methods for constructing plural and singular forms of words. - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + ]]> @@ -71,11 +71,11 @@ Creates a that applies language rules that correspond to the specified . The newly created object. - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + ]]> @@ -109,11 +109,11 @@ Gets or sets the culture. An object that specifies which language rules to apply for singulars and plurals. - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + ]]> @@ -142,13 +142,13 @@ if the word is plural; otherwise, . - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - - Both the and methods can return `true` for the same word. For example, both methods will return `true` for the word "fish". - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + + Both the and methods can return `true` for the same word. For example, both methods will return `true` for the word "fish". + ]]> @@ -177,13 +177,13 @@ if the word is singular; otherwise, . - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - - Both the and methods can return `true` for the same word. For example, both methods will return `true` for the word "fish". - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + + Both the and methods can return `true` for the same word. For example, both methods will return `true` for the word "fish". + ]]> @@ -211,11 +211,11 @@ Returns the plural form of the specified word. The plural form of the input parameter. - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + ]]> @@ -243,11 +243,11 @@ Returns the singular form of the specified word. The singular form of the input parameter. - class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. - + class applies English rules for constructing plural and singular forms of words. To extend the service to other languages, use the on the class. + ]]> diff --git a/xml/System.Data.EntityClient/EntityConnection.xml b/xml/System.Data.EntityClient/EntityConnection.xml index 4e6f7af2290..77e89c4ca29 100644 --- a/xml/System.Data.EntityClient/EntityConnection.xml +++ b/xml/System.Data.EntityClient/EntityConnection.xml @@ -22,9 +22,9 @@ ## Remarks To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case, the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case, the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -50,9 +50,9 @@ ## Remarks To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -83,9 +83,9 @@ ## Remarks To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -122,9 +122,9 @@ To avoid inadvertently putting objects and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through this constructor (), which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through this constructor (), which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -164,9 +164,9 @@ To avoid inadvertently putting objects such as and out of sync with their metadata, the must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through this constructor (), which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through this constructor (), which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -248,9 +248,9 @@ method uses the transaction isolation level. To specify a different isolation level, call . This value might be interpreted differently by different underlying providers. If you want your application to be portable across multiple providers, it should explicitly specify the transaction isolation level by calling . + The method uses the transaction isolation level. To specify a different isolation level, call . This value might be interpreted differently by different underlying providers. If you want your application to be portable across multiple providers, it should explicitly specify the transaction isolation level by calling . - At any particular moment there can be no more than one active transaction that was created through . An attempt to call any of the overloads on an that already has a current transaction results in an . + At any particular moment there can be no more than one active transaction that was created through . An attempt to call any of the overloads on an that already has a current transaction results in an . ]]> @@ -292,7 +292,7 @@ . An attempt to call any of the overloads on an that already has a current transaction results in an . + At any particular moment there can be no more than one active transaction that was created through . An attempt to call any of the overloads on an that already has a current transaction results in an . ]]> @@ -333,7 +333,7 @@ method is required when deriving from . This method is not supported and will raise a . + The method is required when deriving from . This method is not supported and will raise a . ]]> @@ -363,7 +363,7 @@ does nothing. + If the underlying data provider is not known, the call to does nothing. ]]> @@ -393,7 +393,7 @@ . + An `EntityClient` connection string consists of a sequence of keyword/value parameter pairs separated by semicolons. The equals sign (=) connects each keyword and its value. The following table lists the valid names for keyword values in the . |Keyword|Description| |-------------|-----------------| @@ -419,9 +419,9 @@ Provider Connection String= 'Data Source=localhost; To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -714,9 +714,9 @@ Provider Connection String= 'Data Source=localhost; To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string may be changed multiple times before the connection is opened. or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string may be changed multiple times before the connection is opened. or locks the metadata. -- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. @@ -750,9 +750,9 @@ Provider Connection String= 'Data Source=localhost; ## Remarks To avoid inadvertently putting objects such as and out of sync with their metadata, must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked: -- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. +- The instance is constructed through the parameterless constructor, or through the constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling or locks the metadata. -- The instance is constructed through the constructor, which that accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. +- The instance is constructed through the constructor, which that accepts a and a . In this case the metadata is locked at construction time. No changes to the connection string are ever allowed. When metadata is loaded, the verifies that the conceptual model, the storage model, and the mapping file are all present. diff --git a/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml b/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml index 747a7a5759b..ca9f789bcae 100644 --- a/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml +++ b/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml @@ -110,7 +110,7 @@ . + The supplied `connectionString` is not checked for valid keyword/value pairs. For valid keyword/value syntax, see . The invariant Provider name must be specified in the `connectionString` parameter. Supported providers include the following: @@ -155,7 +155,7 @@ method removes all keyword/value pairs from the and resets all corresponding properties to null (`Nothing` in Visual Basic). + The method removes all keyword/value pairs from the and resets all corresponding properties to null (`Nothing` in Visual Basic). ]]> @@ -242,7 +242,7 @@ ## Remarks Because the contains a fixed-size dictionary, trying to add a key that does not exist in the dictionary throws a . - For valid keyword/value syntax, see . + For valid keyword/value syntax, see . ]]> @@ -276,7 +276,7 @@ . + For valid keyword/value syntax, see . ]]> @@ -315,7 +315,7 @@ . + For valid keyword/value syntax, see . ]]> @@ -354,7 +354,7 @@ . + For valid keyword/value syntax, see . ]]> @@ -396,7 +396,7 @@ ## Remarks The invariant provider name is used retrieve the object for the underlying provider. - For valid keyword/value syntax, see . + For valid keyword/value syntax, see . ]]> @@ -438,7 +438,7 @@ ## Remarks The provider-specific connection string is not checked for valid keyword/value pairs before it is set. Developers can create connection strings by using either a strongly typed connection string builder class, or they can use the class. The performs no checks for valid keyword/value pairs. Therefore, it is possible using this class to create invalid connection strings. - For valid keyword/value syntax, see . + For valid keyword/value syntax, see . ]]> @@ -512,7 +512,7 @@ method lets developers safely retrieve a value from a without having to verify that the supplied key name is a valid key name. `TryGetValue` does not raise an exception when it is passed a nonexistent key. Calling `TryGetValue` with a nonexistent key puts the value null (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from a without having to verify that the supplied key name is a valid key name. `TryGetValue` does not raise an exception when it is passed a nonexistent key. Calling `TryGetValue` with a nonexistent key puts the value null (`Nothing` in Visual Basic) in the `value` parameter. ]]> diff --git a/xml/System.Data.EntityClient/EntityDataReader.xml b/xml/System.Data.EntityClient/EntityDataReader.xml index 84c75bf038f..279fa593f7d 100644 --- a/xml/System.Data.EntityClient/EntityDataReader.xml +++ b/xml/System.Data.EntityClient/EntityDataReader.xml @@ -35,11 +35,11 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). +- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). -- only closes the , without consuming any pending records or result sets. +- only closes the , without consuming any pending records or result sets. -- only disposes of the , without consuming any pending records or result sets. +- only disposes of the , without consuming any pending records or result sets. For code examples, see [Working with EntityClient](https://learn.microsoft.com/previous-versions/bb738679(v=vs.90)). @@ -74,11 +74,11 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exception, will wrap it in (or a derived exception). +- calls the only when is explicitly called. If throws an exception, will wrap it in (or a derived exception). -- only closes the , without consuming any pending records or result sets. +- only closes the , without consuming any pending records or result sets. -- only disposes of the , without consuming any pending records or result sets. +- only disposes of the , without consuming any pending records or result sets. ]]> @@ -169,11 +169,11 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). +- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). -- only closes the , without consuming any pending records or result sets. +- only closes the , without consuming any pending records or result sets. -- only disposes of the , without consuming any pending records or result sets. +- only disposes of the , without consuming any pending records or result sets. ]]> diff --git a/xml/System.Data.Linq.Mapping/AssociationAttribute.xml b/xml/System.Data.Linq.Mapping/AssociationAttribute.xml index 9233a55c2d5..024997b9afd 100644 --- a/xml/System.Data.Linq.Mapping/AssociationAttribute.xml +++ b/xml/System.Data.Linq.Mapping/AssociationAttribute.xml @@ -255,7 +255,7 @@ ## Remarks For multiple members, use a comma-separated list. - The key is not required to match the primary key or foreign key, but the user-stated cardinality (0-1 for or 0-n for ) is assumed to be true. + The key is not required to match the primary key or foreign key, but the user-stated cardinality (0-1 for or 0-n for ) is assumed to be true. @@ -302,7 +302,7 @@ ## Remarks For multiple members, use a comma-separated list. - The key is not required to match the primary key or foreign key, but the user-stated cardinality (0-1 for or 0-n for ) is assumed to be true. + The key is not required to match the primary key or foreign key, but the user-stated cardinality (0-1 for or 0-n for ) is assumed to be true. diff --git a/xml/System.Data.Linq.Mapping/ColumnAttribute.xml b/xml/System.Data.Linq.Mapping/ColumnAttribute.xml index 560e134b7c9..6d6c2853176 100644 --- a/xml/System.Data.Linq.Mapping/ColumnAttribute.xml +++ b/xml/System.Data.Linq.Mapping/ColumnAttribute.xml @@ -180,7 +180,7 @@ public class Employees If you set this value to `false`, the data in the corresponding column is assumed to be non-null. > [!NOTE] -> This property is duplicated from the property for convenience. The method uses only the property. For this reason, you must specify whether a column can contain null values in the property also. +> This property is duplicated from the property for convenience. The method uses only the property. For this reason, you must specify whether a column can contain null values in the property also. @@ -225,9 +225,9 @@ public class Employees property only if you plan to use to create an instance of the database. + Use this property to specify the exact text that defines the column in a Transact-SQL table declaration. Specify the property only if you plan to use to create an instance of the database. - The default value of is inferred from the member type. For more information, see [SQL-CLR Type Mapping](/dotnet/framework/data/adonet/sql/linq/sql-clr-type-mapping). + The default value of is inferred from the member type. For more information, see [SQL-CLR Type Mapping](/dotnet/framework/data/adonet/sql/linq/sql-clr-type-mapping). @@ -272,7 +272,7 @@ public class Employees to define a column as containing computed values. + Use this property when you use to define a column as containing computed values. For example, if you want to create a column defined in SQL as `InventoryVal AS UnitPrice * UnitsInStock`, use the following *expression* string: `"UnitPrice * UnitsInStock"`. @@ -322,10 +322,10 @@ public class Employees members are synchronized immediately after the row of data is inserted, and the members are available after is completed. + members are synchronized immediately after the row of data is inserted, and the members are available after is completed. > [!NOTE] -> If the column holds primary key values and you designate as `true`, you should also add the property by using the `IDENTITY` modifier. +> If the column holds primary key values and you designate as `true`, you should also add the property by using the `IDENTITY` modifier. @@ -471,9 +471,9 @@ public class Employees Note the following when `IsVersion` is true: -- Use to specify the correct modifiers to designate a version number or timestamp column. If you do not specify , LINQ to SQL infers the correct modifiers. +- Use to specify the correct modifiers to designate a version number or timestamp column. If you do not specify , LINQ to SQL infers the correct modifiers. - Version numbers are incremented and timestamp columns are updated every time that the associated row is updated. Members with `IsVersion=true` are synchronized immediately after the data row is updated. The new values are visible after finishes. + Version numbers are incremented and timestamp columns are updated every time that the associated row is updated. Members with `IsVersion=true` are synchronized immediately after the data row is updated. The new values are visible after finishes. diff --git a/xml/System.Data.Linq.Mapping/InheritanceMappingAttribute.xml b/xml/System.Data.Linq.Mapping/InheritanceMappingAttribute.xml index b5cd92f5a7b..a0954362d1b 100644 --- a/xml/System.Data.Linq.Mapping/InheritanceMappingAttribute.xml +++ b/xml/System.Data.Linq.Mapping/InheritanceMappingAttribute.xml @@ -38,7 +38,7 @@ - You can skip a class in the hierarchy when you map classes, but you can query against mapped classes only. - For correct materialization, discriminator code values must be unique and match the values in the database. A row with a discriminator code value that does not exactly match (even by casing) instantiates the class by using set to `true`. + For correct materialization, discriminator code values must be unique and match the values in the database. A row with a discriminator code value that does not exactly match (even by casing) instantiates the class by using set to `true`. @@ -146,7 +146,7 @@ attributes must be declared with as `true`. + Exactly one of the attributes must be declared with as `true`. ]]> diff --git a/xml/System.Data.Linq.Mapping/MetaDataMember.xml b/xml/System.Data.Linq.Mapping/MetaDataMember.xml index 49aaea21cd5..68ae407ef43 100644 --- a/xml/System.Data.Linq.Mapping/MetaDataMember.xml +++ b/xml/System.Data.Linq.Mapping/MetaDataMember.xml @@ -430,7 +430,7 @@ ## Remarks If this property is `true`, the class member represents a column that is part of the table's unique key. More than one member of the class can have this property set to `true` for a key that is a composite of the associated columns. For an entity class, at least one member must have this attribute and should be mapped to the primary key or a unique key in the corresponding table or view. Otherwise, LINQ to SQL considers instances of the class as read-only for the purpose of submitting changes to the database. - The set of columns identified with are not required to be the primary key. They simply denote a set that uniquely identifies the entity. Common alternatives include clustering index columns or other unique key columns. + The set of columns identified with are not required to be the primary key. They simply denote a set that uniquely identifies the entity. Common alternatives include clustering index columns or other unique key columns. ]]> @@ -687,7 +687,7 @@ set to `true`), detection is done by comparing original member values with the current database state. + If the class does not have a version member ( set to `true`), detection is done by comparing original member values with the current database state. The property determines how LINQ to SQL implements conflict detection under optimistic concurrency. Only those members with this property set to or are considered during conflict detection. diff --git a/xml/System.Data.Linq.Mapping/ParameterAttribute.xml b/xml/System.Data.Linq.Mapping/ParameterAttribute.xml index ab12da18100..d7d57cc92e2 100644 --- a/xml/System.Data.Linq.Mapping/ParameterAttribute.xml +++ b/xml/System.Data.Linq.Mapping/ParameterAttribute.xml @@ -111,11 +111,11 @@ Gets or sets the name of the parameter. The name as a string. - , the name is assumed to be the same as the name of the parameter in the database. - + , the name is assumed to be the same as the name of the parameter in the database. + ]]> diff --git a/xml/System.Data.Linq.Mapping/TableAttribute.xml b/xml/System.Data.Linq.Mapping/TableAttribute.xml index 3bf727f0eba..a48fa4fb38b 100644 --- a/xml/System.Data.Linq.Mapping/TableAttribute.xml +++ b/xml/System.Data.Linq.Mapping/TableAttribute.xml @@ -82,10 +82,10 @@ , the table name is assumed to be the same as the class name. + If you do not specify a name by using , the table name is assumed to be the same as the class name. > [!NOTE] -> You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the string is considered to be the schema name, and the rest to be the table name. +> You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the string is considered to be the schema name, and the rest to be the table name. In the following example, the default table name, `Customer`, is changed to `Customers`. diff --git a/xml/System.Data.Linq/ChangeConflictCollection.xml b/xml/System.Data.Linq/ChangeConflictCollection.xml index feff2f2ed6f..dcf97212985 100644 --- a/xml/System.Data.Linq/ChangeConflictCollection.xml +++ b/xml/System.Data.Linq/ChangeConflictCollection.xml @@ -34,14 +34,14 @@ Returns a collection of objects involved in concurrency conflicts. - @@ -129,13 +129,13 @@ The array index where the copy is to start. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -341,13 +341,13 @@ The item to add. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -376,11 +376,11 @@ if the collection is read-only. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -439,11 +439,11 @@ if access to the collection is synchronized (thread-safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -471,11 +471,11 @@ For a description of this member, see . An object that can be used to synchronize access to the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -504,11 +504,11 @@ For a description of this member, see . An enumerator that iterates through a collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data.Linq/CompiledQuery.xml b/xml/System.Data.Linq/CompiledQuery.xml index bc999867c9d..74f7bc0b522 100644 --- a/xml/System.Data.Linq/CompiledQuery.xml +++ b/xml/System.Data.Linq/CompiledQuery.xml @@ -17,14 +17,14 @@ Provides for compilation and caching of queries for reuse. - method to create a new delegate to represent the compiled query. - + method to create a new delegate to represent the compiled query. + > [!NOTE] -> Compilation does not occur until the first time the query is executed. - +> Compilation does not occur until the first time the query is executed. + ]]> @@ -63,16 +63,16 @@ Compiles the query. A generic delegate that represents the compiled query. - - - - -## Examples - See - + + + + +## Examples + See + ]]> @@ -113,16 +113,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -165,16 +165,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -219,16 +219,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -274,16 +274,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -331,16 +331,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -390,16 +390,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -451,16 +451,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -514,16 +514,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -579,16 +579,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -646,16 +646,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -715,16 +715,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -786,16 +786,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -859,16 +859,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -934,16 +934,16 @@ Compiles the query. A generic delegate that represents the compiled query. - . - - - -## Examples - See . - + . + + + +## Examples + See . + ]]> @@ -1011,16 +1011,16 @@ Compiles the query. A generic delegate that represents the compiled query. - - - - -## Examples - See - + + + + +## Examples + See + ]]> diff --git a/xml/System.Data.Linq/DataContext.xml b/xml/System.Data.Linq/DataContext.xml index fa6b0105948..a55d4ed010c 100644 --- a/xml/System.Data.Linq/DataContext.xml +++ b/xml/System.Data.Linq/DataContext.xml @@ -209,9 +209,9 @@ . + This property gets or sets the command time-out (in seconds) used to execute generated commands (`IDbCommands`). For more information, see . - When this property is not set, the default value of is used for query command execution. This default value is set by the storage provider. Note that some providers may throw exceptions if this value is set to a non-zero value. + When this property is not set, the default value of is used for query command execution. This default value is set by the storage provider. Note that some providers may throw exceptions if this value is set to a non-zero value. ]]> @@ -334,7 +334,7 @@ method is used in automatically generated code and acts as a proxy to database functions. + The method is used in automatically generated code and acts as a proxy to database functions. ]]> @@ -413,9 +413,9 @@ ## Valid modes Deferred loading requires object tracking. Only the following three modes are valid: -- = `false`. is ignored and inferred to be `false`. This behavior corresponds to a read-only . +- = `false`. is ignored and inferred to be `false`. This behavior corresponds to a read-only . -- = `true`. = `false`. This situation corresponds to a that allows users to load an object graph by using directives, but it does not enable deferred loading. +- = `true`. = `false`. This situation corresponds to a that allows users to load an object graph by using directives, but it does not enable deferred loading. - Both are set to `true`. This is the default. @@ -626,7 +626,7 @@ The following example opens a connection and passes a SQL `UPDATE` command to th . + See . ]]> @@ -662,11 +662,11 @@ The following example opens a connection and passes a SQL `UPDATE` command to th - Because the method has a protected modifier, its use requires subclassing . -- An exception is thrown if this operation is not called inside a operation. It is not intended to be called as a stand-alone operation outside the scope of a operation. itself calls override methods if they are implemented and the previous methods are intended to be called inside the override methods. +- An exception is thrown if this operation is not called inside a operation. It is not intended to be called as a stand-alone operation outside the scope of a operation. itself calls override methods if they are implemented and the previous methods are intended to be called inside the override methods. - It is the responsibility of the developer to pass in the correct entity. The implementation verifies that the passed-in entity is tracked. However, it is the responsibility of the developer to maintain the order or pass in the same entity two times. -- It is the responsibility of the developer to invoke the correct dynamic API. For example, in the `Update` override method, only the method can be called. LINQ to SQL does not detect or verify whether the invoked dynamic method matches the applicable operation. The results are undefined if an inapplicable method is called (for example, calling for an object to be updated). +- It is the responsibility of the developer to invoke the correct dynamic API. For example, in the `Update` override method, only the method can be called. LINQ to SQL does not detect or verify whether the invoked dynamic method matches the applicable operation. The results are undefined if an inapplicable method is called (for example, calling for an object to be updated). ]]> @@ -698,7 +698,7 @@ The following example opens a connection and passes a SQL `UPDATE` command to th . + See . ]]> @@ -742,7 +742,7 @@ The following example opens a connection and passes a SQL `UPDATE` command to th method is used in automatically generated code and acts as a proxy to database functions. + The method is used in automatically generated code and acts as a proxy to database functions. ]]> @@ -933,17 +933,17 @@ Next ## Remarks Note the following considerations: -- might have side effects, such as inference of insert and delete operations that are usually performed at the time of . For example, objects that are used in the following operations can create corresponding inferred operations in the following list: +- might have side effects, such as inference of insert and delete operations that are usually performed at the time of . For example, objects that are used in the following operations can create corresponding inferred operations in the following list: - - to . + - to . - - assignment to null (possibly because of to . + - assignment to null (possibly because of to . - The set may not be ordered according to foreign key constraints. - Database-generated values (for example, primary and foreign key values, timestamps, and so forth) are not available. Such information requires database command execution and perhaps the propagation of retrieved information (for example, foreign key from primary key). -- The set of changed objects is computed at the time of the call. Subsequent calls to can produce a different set if additional changes are made. +- The set of changed objects is computed at the time of the call. Subsequent calls to can produce a different set if additional changes are made. Output when no changes have been made appears as follows: @@ -994,7 +994,7 @@ Next - Normal query translation exceptions thrown during LINQ to SQL query execution apply for a query that cannot be translated. -- Only the first query command is returned. Specifically, additional commands that are used for eager loading () are not included. +- Only the first query command is returned. Specifically, additional commands that are used for eager loading () are not included. - does not track what the user does with the command. For example, results from the execution of the returned command are not tracked and do not affect state. @@ -1035,7 +1035,7 @@ Next . It is important to have a weakly typed version because it is a relatively common practice to construct queries dynamically. It would be inconvenient to force the application to use reflection to call the correct generic method. + This is a weakly typed version of . It is important to have a weakly typed version because it is a relatively common practice to construct queries dynamically. It would be inconvenient to force the application to use reflection to call the correct generic method. If there is no collection for a particular type, an exception is thrown. @@ -1203,11 +1203,11 @@ Next For more information, see the Valid Modes section in . -- If the property is set to `false` and is called. +- If the property is set to `false` and is called. - If is `false`, is ignored and treated as `false`. In this case, the is read-only. + If is `false`, is ignored and treated as `false`. In this case, the is read-only. - If is `true`, is `false`. In this case, allows you to load an object graph by using directives, but does not enable deferred loading. + If is `true`, is `false`. In this case, allows you to load an object graph by using directives, but does not enable deferred loading. ]]> @@ -1332,9 +1332,9 @@ Next executes these methods instead of the default LINQ to SQL commands. + If override methods are present for insert, update, or delete, executes these methods instead of the default LINQ to SQL commands. - starts a transaction and will roll back if an exception occurs while is executing. However, this does not roll back the changes in memory or tracked by the ; those changes will need to be rolled back manually. You can start with a new instance of the if the changes in memory are to be discarded. + starts a transaction and will roll back if an exception occurs while is executing. However, this does not roll back the changes in memory or tracked by the ; those changes will need to be rolled back manually. You can start with a new instance of the if the changes in memory are to be discarded. ]]> @@ -1363,7 +1363,7 @@ Next executes these methods instead of the default LINQ to SQL commands. + If override methods are present for insert, update, or delete, executes these methods instead of the default LINQ to SQL commands. ]]> @@ -1457,27 +1457,27 @@ Next is converted to an object in the . + Each row in the is converted to an object in the . ```csharp public IEnumerable Translate(IDataReader reader) {} ``` - Description: This method is used to convert an existing to objects. Each row in the is converted to an object in the . + Description: This method is used to convert an existing to objects. Each row in the is converted to an object in the . **Generic parameters:** - `T`: See . + `T`: See . **Parameters:** - `Query`: See the description for command under . + `Query`: See the description for command under . - `Parameters`: See the description for parameters under . + `Parameters`: See the description for parameters under . **Return type:** - : collection of objects returned by the conversion. + : collection of objects returned by the conversion. ]]> diff --git a/xml/System.Data.Linq/DataLoadOptions.xml b/xml/System.Data.Linq/DataLoadOptions.xml index 7dfa2e5efa5..4866d13ff27 100644 --- a/xml/System.Data.Linq/DataLoadOptions.xml +++ b/xml/System.Data.Linq/DataLoadOptions.xml @@ -227,7 +227,7 @@ methods. + You cannot specify the loading of two levels of relationships (for example, `Orders.OrderDetails`). In these scenarios you must specify two separate methods. To avoid cycling, see Remarks section in . diff --git a/xml/System.Data.Linq/EntityRef`1.xml b/xml/System.Data.Linq/EntityRef`1.xml index 5b2b0021cc4..64cfde76e76 100644 --- a/xml/System.Data.Linq/EntityRef`1.xml +++ b/xml/System.Data.Linq/EntityRef`1.xml @@ -25,11 +25,11 @@ The type of the target entity. Provides for deferred loading and relationship maintenance for the singleton side of a one-to-many relationship in a LINQ to SQL application. - . - + . + ]]> @@ -152,11 +152,11 @@ if the target has been loaded or assigned. - diff --git a/xml/System.Data.Linq/EntitySet`1.xml b/xml/System.Data.Linq/EntitySet`1.xml index eb2ad0fd567..a6cb9740725 100644 --- a/xml/System.Data.Linq/EntitySet`1.xml +++ b/xml/System.Data.Linq/EntitySet`1.xml @@ -54,11 +54,11 @@ The data type of the target entity. Provides for deferred loading and relationship maintenance for the collection side of one-to-many and one-to-one relationships in a LINQ to SQL applications. - . - + . + ]]> @@ -288,30 +288,30 @@ The starting index in the array. Copies the to an array. - @@ -412,11 +412,11 @@ customer.Orders.CopyTo(orderArray, 0) if the has either loaded or assigned a value; otherwise, . - @@ -689,11 +689,11 @@ customer.Orders.CopyTo(orderArray, 0) if the collection is read-only; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -726,11 +726,11 @@ customer.Orders.CopyTo(orderArray, 0) The array index at which copying begins. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -759,11 +759,11 @@ customer.Orders.CopyTo(orderArray, 0) if access to the collection is synchronized (thread-safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -791,11 +791,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . An object that can be used to synchronize access to the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -830,11 +830,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . An object that can be used to iterate through a collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -866,11 +866,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . The position into which the new element was inserted. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -903,11 +903,11 @@ customer.Orders.CopyTo(orderArray, 0) if the is found in the ; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -939,11 +939,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . The index of if found in the list; otherwise, -1. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -976,11 +976,11 @@ customer.Orders.CopyTo(orderArray, 0) The object to insert into the list. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1009,11 +1009,11 @@ customer.Orders.CopyTo(orderArray, 0) if the collection has a fixed size; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1042,11 +1042,11 @@ customer.Orders.CopyTo(orderArray, 0) if the collection is read-only; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1078,11 +1078,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . The element at the specified index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1113,11 +1113,11 @@ customer.Orders.CopyTo(orderArray, 0) The object to remove from the list. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1146,11 +1146,11 @@ customer.Orders.CopyTo(orderArray, 0) if the collection is a collection of objects; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1179,11 +1179,11 @@ customer.Orders.CopyTo(orderArray, 0) For a description of this member, see . An that can be bound to a data source from the object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml b/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml index 59b78ee9852..6d0e0347d2e 100644 --- a/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml +++ b/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml @@ -59,8 +59,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -100,8 +100,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -145,8 +145,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Data.Linq/IMultipleResults.xml b/xml/System.Data.Linq/IMultipleResults.xml index 0d0c5e9c8a9..49a3b7f66e7 100644 --- a/xml/System.Data.Linq/IMultipleResults.xml +++ b/xml/System.Data.Linq/IMultipleResults.xml @@ -21,27 +21,27 @@ Represents the results of mapped functions or queries with variable return sequences. - @@ -71,20 +71,20 @@ else if(@shape = 2) Retrieves the next result as a sequence of a specified type. An enumeration for iterating over the results. - [!NOTE] -> You must use the pattern to obtain an enumerator of the correct type, based on your knowledge of the stored procedure. - - - -## Examples +> You must use the pattern to obtain an enumerator of the correct type, based on your knowledge of the stored procedure. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/IMultipleResults/Overview/Program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqSprox/vb/Module1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqSprox/vb/Module1.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Data.Linq/ITable.xml b/xml/System.Data.Linq/ITable.xml index 013365456c5..6af0c68734f 100644 --- a/xml/System.Data.Linq/ITable.xml +++ b/xml/System.Data.Linq/ITable.xml @@ -24,7 +24,7 @@ . + For more information about methods, see . ]]> @@ -43,7 +43,7 @@ ## Remarks For more information about how to use this method, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - If a required member is missing, a is thrown during . + If a required member is missing, a is thrown during . ]]> @@ -274,7 +274,7 @@ to perform the actual deletion in the database. + Call to perform the actual deletion in the database. ]]> @@ -306,7 +306,7 @@ to perform the actual deletion in the database. + Disconnected entities must be attached before they can be deleted. Call to perform the actual deletion in the database. ]]> @@ -401,7 +401,7 @@ to perform the actual insertion into the database. + Call to perform the actual insertion into the database. ]]> @@ -433,7 +433,7 @@ to perform the actual insertion into the database. + Call to perform the actual insertion into the database. ]]> diff --git a/xml/System.Data.Linq/ITable`1.xml b/xml/System.Data.Linq/ITable`1.xml index 77ee994e485..35100b8c5f9 100644 --- a/xml/System.Data.Linq/ITable`1.xml +++ b/xml/System.Data.Linq/ITable`1.xml @@ -38,11 +38,11 @@ The type of the data in the table. Represents a table for a particular type in the underlying database. - . - + . + ]]> @@ -69,11 +69,11 @@ The object to be added. When overridden, attaches a disconnected or "detached" entity to a new when original values are required for optimistic concurrency checks. - . - + . + ]]> @@ -100,11 +100,11 @@ The object to delete. When overridden, puts an entity from this table into a state. - . - + . + ]]> @@ -131,11 +131,11 @@ The object to insert. When overridden, adds an entity in a state to this . - . - + . + ]]> diff --git a/xml/System.Data.Linq/Link`1.xml b/xml/System.Data.Linq/Link`1.xml index 528e2ee7974..9ab6e6a493c 100644 --- a/xml/System.Data.Linq/Link`1.xml +++ b/xml/System.Data.Linq/Link`1.xml @@ -24,7 +24,7 @@ ) to , loads the value by enumerating the source the first time the property is accessed. + If you assign a deferred source () to , loads the value by enumerating the source the first time the property is accessed. ]]> @@ -64,7 +64,7 @@ with a deferred value loader (implements ) + Use this constructor to initialize the with a deferred value loader (implements ) ]]> @@ -147,7 +147,7 @@ ## Remarks "Loaded" means that the data was loaded during materialization or at deferred loading. "Assigned" means that you have manually given the data a value. - LINQ to SQL uses this property to make sure that the has a value, so that accessing it will not trigger deferred loading. + LINQ to SQL uses this property to make sure that the has a value, so that accessing it will not trigger deferred loading. ]]> diff --git a/xml/System.Data.Linq/MemberChangeConflict.xml b/xml/System.Data.Linq/MemberChangeConflict.xml index 5bf4073f22b..384cb6f5093 100644 --- a/xml/System.Data.Linq/MemberChangeConflict.xml +++ b/xml/System.Data.Linq/MemberChangeConflict.xml @@ -17,17 +17,17 @@ Represents a situation in which an attempted update fails because member values have been updated since the client last read them. - @@ -109,11 +109,11 @@ if the member data has been changed. - @@ -145,11 +145,11 @@ if the conflict has been resolved. - @@ -236,29 +236,29 @@ See . Uses a parameter to automatically specify the value to set as the current value for the member in conflict. - . - - - -## Examples - The following example overwrites current values with values from the database. - + . + + + +## Examples + The following example overwrites current values with values from the database. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet1"::: - - The following example shows how to swap the original value with the values retrieved from the database. No current value is modified. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet1"::: + + The following example shows how to swap the original value with the values retrieved from the database. No current value is modified. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet2"::: - - The following example keeps the current values that have been changed, but updates the other values with database values. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet2"::: + + The following example keeps the current values that have been changed, but updates the other values with database values. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet3"::: + ]]> @@ -286,11 +286,11 @@ The value to set as the current value. Specifies the value to set as the current value for the member in conflict. - operation. - + operation. + ]]> diff --git a/xml/System.Data.Linq/RefreshMode.xml b/xml/System.Data.Linq/RefreshMode.xml index 0f0677fce2e..3ae5f44d7ec 100644 --- a/xml/System.Data.Linq/RefreshMode.xml +++ b/xml/System.Data.Linq/RefreshMode.xml @@ -16,29 +16,29 @@ Defines how the method handles optimistic concurrency conflicts. - overloads. - - - -## Examples - The following example overwrites current values with values from the database. - + overloads. + + + +## Examples + The following example overwrites current values with values from the database. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet1"::: - - The following example shows how to swap the original value with the values retrieved from the database. No current value is modified. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet1"::: + + The following example shows how to swap the original value with the values retrieved from the database. No current value is modified. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet2"::: - - The following example keeps the current values that have been changed, but updates the other values with database values. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet2"::: + + The following example keeps the current values that have been changed, but updates the other values with database values. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/MemberChangeConflict/Resolve/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.refreshmode/vb/module1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Data.Linq/Table`1.xml b/xml/System.Data.Linq/Table`1.xml index a419c9e8dfb..486c190ffe9 100644 --- a/xml/System.Data.Linq/Table`1.xml +++ b/xml/System.Data.Linq/Table`1.xml @@ -59,16 +59,16 @@ The type of the data in the table. Represents a table for a particular type in the underlying database. - instance via or by using a strongly typed property for the strongly typed . That is, when the designer generates a DataContext object, it generates properties to represent each Table. For example: - + instance via or by using a strongly typed property for the strongly typed . That is, when the designer generates a DataContext object, it generates properties to represent each Table. For example: + ```csharp -[global::System.Data.Linq.Mapping.DatabaseAttribute(Name="SignOffTool")] -public partial class DataClasses1DataContext : System.Data.Linq.DataContext +[global::System.Data.Linq.Mapping.DatabaseAttribute(Name="SignOffTool")] +public partial class DataClasses1DataContext : System.Data.Linq.DataContext { public System.Data.Linq.Table Users { @@ -79,9 +79,9 @@ public partial class DataClasses1DataContext : System.Data.Linq.DataContext } } ``` - - For this strongly typed DataContext, you can access the Users property to get `Table`. - + + For this strongly typed DataContext, you can access the Users property to get `Table`. + ]]> @@ -94,61 +94,61 @@ public partial class DataClasses1DataContext : System.Data.Linq.DataContext Attaches an entity to the . - , serialized to a client, and then deserialized back (with the intention to perform an update or delete operation). For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - - Do not try to `Attach` an entity that has not been detached through serialization. Entities that have not been serialized still maintain associations with deferred loaders that can cause unexpected results if the entity becomes tracked by a second data context. - - When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - + , serialized to a client, and then deserialized back (with the intention to perform an update or delete operation). For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + + Do not try to `Attach` an entity that has not been detached through serialization. Entities that have not been serialized still maintain associations with deferred loaders that can cause unexpected results if the entity becomes tracked by a second data context. + + When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + `Attach` attaches all entities in the object graph of the provided object. For example: - + ```csharp using (var db = new SampleDataContext()) -{ - var employee = new Employee { employeeId = 1 }; - - var master = new Master(); - master.Employee = employee; - - var child = new Child(); - child.Employee = employee; - - db.Employees.Attach(employee); - - master.Child = child; - - db.Masters.InsertOnSubmit(master); - - db.SubmitChanges(); -} -``` +{ + var employee = new Employee { employeeId = 1 }; + + var master = new Master(); + master.Employee = employee; + + var child = new Child(); + child.Employee = employee; + + db.Employees.Attach(employee); + + master.Child = child; + + db.Masters.InsertOnSubmit(master); + + db.SubmitChanges(); +} +``` ```vb Using db As New SampleDataContext() Dim employee As New Employee With { .employeeId = 1 } - - Dim master As New Master() - master.Employee = employee - - Dim child As New Child() - child.Employee = employee - - db.Employees.Attach(employee) - - master.Child = child - - db.Masters.InsertOnSubmit(master) - - db.SubmitChanges() - -End Using -``` - - Calling `Attach` on `Employee` attaches employee, master, and child, because the `Employee` has relationships to both master and child. You must explicitly call `InsertOnSubmit` to change the state from attached to inserted. - + + Dim master As New Master() + master.Employee = employee + + Dim child As New Child() + child.Employee = employee + + db.Employees.Attach(employee) + + master.Child = child + + db.Masters.InsertOnSubmit(master) + + db.SubmitChanges() + +End Using +``` + + Calling `Attach` on `Employee` attaches employee, master, and child, because the `Employee` has relationships to both master and child. You must explicitly call `InsertOnSubmit` to change the state from attached to inserted. + ]]> @@ -182,17 +182,17 @@ End Using The original values of the entity to be attached. Attaches a disconnected or "detached" entity to a new when original values are required for optimistic concurrency checks. - , serialized to a client, and then deserialized back to perform an update or delete operation. Because the new has no way of tracking what the original values were for a disconnected entity, the client is responsible for supplying those values. In this version of , the entity is assumed to be in its original value state. After calling this method, you can then update its fields, for example with additional data sent from the client. - - When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - - For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - - Do not try to `Attach` an entity that has not been detached through serialization. Entities that have not been serialized still maintain associations with deferred loaders that can cause unexpected results if the entity becomes tracked by a second data context. - + , serialized to a client, and then deserialized back to perform an update or delete operation. Because the new has no way of tracking what the original values were for a disconnected entity, the client is responsible for supplying those values. In this version of , the entity is assumed to be in its original value state. After calling this method, you can then update its fields, for example with additional data sent from the client. + + When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + + For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + + Do not try to `Attach` an entity that has not been detached through serialization. Entities that have not been serialized still maintain associations with deferred loaders that can cause unexpected results if the entity becomes tracked by a second data context. + ]]> @@ -223,11 +223,11 @@ End Using to attach the entity as modified; to attach the entity as unmodified. Attaches an entity to the in either a modified or unmodified state. - is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - + is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + ]]> @@ -257,19 +257,19 @@ End Using An instance of the same entity type with data members that contain the original values. Attaches an entity to the in either a modified or unmodified state by specifying both the entity and its original state. - is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - - - -## Examples + is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/Attach/Program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet4"::: + ]]> @@ -282,15 +282,15 @@ End Using Attaches all entities of a collection to the in either a modified or unmodified state. - is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - - For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - + is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + + For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + ]]> @@ -326,13 +326,13 @@ End Using The collection of entities. Attaches all entities of a collection to the in either a modified or unmodified state. - . When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - - For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - + . When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + + For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + ]]> @@ -371,31 +371,31 @@ End Using if the object has a timestamp or RowVersion member; if original values are being used for the optimistic concurrency check. Attaches all entities of a collection to the in either a modified or unmodified state. - in either a *modified* or *unmodified* state. If attaching as modified, the entity must either declare a version member or must not participate in update conflict checking. If attaching as unmodified, the entity is assumed to represent the original value. After calling this method, the entity's fields can be modified with other information from the client before is called. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - - When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. - - - -## Examples - The following example shows how you can update an `Order` object on a different instance. The example assumes that you have a connection to a database and have made a LINQ to SQL file for it (in this case, the Northwind sample database). - + in either a *modified* or *unmodified* state. If attaching as modified, the entity must either declare a version member or must not participate in update conflict checking. If attaching as unmodified, the entity is assumed to represent the original value. After calling this method, the entity's fields can be modified with other information from the client before is called. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + + When a new entity is attached, deferred loaders for any child collections (for example, `EntitySet` collections of entities from associated tables) are initialized. When is called, members of the child collections are put into an `Unmodified` state. To update members of a child collection, you must explicitly call `Attach` and specify that entity. + + + +## Examples + The following example shows how you can update an `Order` object on a different instance. The example assumes that you have a connection to a database and have made a LINQ to SQL file for it (in this case, the Northwind sample database). + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/Attach/Program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet1"::: - - In the following example, an entity object to be attached has a foreign key relation with another object and is stored in the cache but not attached. When you call , the `ChangeProcessor` adds an `Insert` operation for all the foreign key objects. This is a side-effect when an entity instance is re-used in a different instance. For this reason, LINQ to SQL does not support re-use of objects. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet1"::: + + In the following example, an entity object to be attached has a foreign key relation with another object and is stored in the cache but not attached. When you call , the `ChangeProcessor` adds an `Insert` operation for all the foreign key objects. This is a side-effect when an entity instance is re-used in a different instance. For this reason, LINQ to SQL does not support re-use of objects. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/Attach/Program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet7"::: - - The following example shows a scenario in which Customer A has canceled all orders and Customer B has taken ownership of them. You can attach all orders of Customer A at the same time. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet7"::: + + The following example shows a scenario in which Customer A has canceled all orders and Customer B has taken ownership of them. You can attach all orders of Customer A at the same time. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/Attach/Program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqNTier/vb/Module1.vb" id="Snippet3"::: + ]]> @@ -462,33 +462,33 @@ End Using The entities to delete. Puts all entities from the collection into a state. - is called. Disconnected entities must be attached before they can be deleted. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - + is called. Disconnected entities must be attached before they can be deleted. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + ## Examples The following example shows one use for this method: - + ```csharp -IEnumerable customersWithoutOrders = (from c in db.Customers - where c.Orders.Count == 0 - select c).ToList(); - -db.Customers.DeleteAllOnSubmit(customersWithoutOrders); -db.SubmitChanges(); -``` - +IEnumerable customersWithoutOrders = (from c in db.Customers + where c.Orders.Count == 0 + select c).ToList(); + +db.Customers.DeleteAllOnSubmit(customersWithoutOrders); +db.SubmitChanges(); +``` + ```vb -Dim customersWithoutOrders As IEnumerable(Of Customer) = (From c In db.Customers _ - Where c.Orders.Count = 0 _ - Select c).ToList() - -db.Customers.DeleteAllOnSubmit(customersWithoutOrders) -db.SubmitChanges() -``` - +Dim customersWithoutOrders As IEnumerable(Of Customer) = (From c In db.Customers _ + Where c.Orders.Count = 0 _ + Select c).ToList() + +db.Customers.DeleteAllOnSubmit(customersWithoutOrders) +db.SubmitChanges() +``` + ]]> @@ -522,20 +522,20 @@ db.SubmitChanges() The entity to be deleted. Puts an entity from this table into a state. - is called. Disconnected entities must first be attached before they can be deleted. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - + is called. Disconnected entities must first be attached before they can be deleted. For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + > [!NOTE] -> LINQ to SQL does not support or recognize cascade-delete operations. If you want to delete a row in a table that has constraints against it, you must either set the `ON DELETE CASCADE` rule in the foreign-key constraint in the database, or use your own code to first delete the child objects that prevent the parent object from being deleted. Otherwise, an exception is thrown. - - - -## Examples +> LINQ to SQL does not support or recognize cascade-delete operations. If you want to delete a row in a table that has constraints against it, you must either set the `ON DELETE CASCADE` rule in the foreign-key constraint in the database, or use your own code to first delete the child objects that prevent the parent object from being deleted. Otherwise, an exception is thrown. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/DeleteOnSubmit/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.table/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.table/vb/module1.vb" id="Snippet3"::: + ]]> @@ -613,11 +613,11 @@ db.SubmitChanges() Creates a new list for binding to a data source. A new for binding to a data source. - @@ -646,11 +646,11 @@ db.SubmitChanges() Returns a instance that contains the original state of the entity. A instance that contains the original state of the entity. - . The original state of an entity that has been serialized and deserialized must be provided by an independent tracking mechanism and supplied when the entity is attached to a new . For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). - + . The original state of an entity that has been serialized and deserialized must be provided by an independent tracking mechanism and supplied when the entity is attached to a new . For more information, see [Data Retrieval and CUD Operations in N-Tier Applications (LINQ to SQL)](/dotnet/framework/data/adonet/sql/linq/data-retrieval-and-cud-operations-in-n-tier-applications). + ]]> @@ -686,11 +686,11 @@ db.SubmitChanges() The entities to add. Adds all entities of a collection to the in a state. - has been called. - + has been called. + ]]> @@ -724,17 +724,17 @@ db.SubmitChanges() The entity to be added. Adds an entity in a state to this . - has been called. - - - -## Examples + has been called. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/TableTEntity/DeleteOnSubmit/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.table/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.table/vb/module1.vb" id="Snippet1"::: + ]]> @@ -827,11 +827,11 @@ db.SubmitChanges() Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -860,11 +860,11 @@ db.SubmitChanges() if the collection is a collection of objects; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -893,11 +893,11 @@ db.SubmitChanges() Returns an that can be bound to a data source from an object that does not implement an itself. An that can be bound to a data source. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -937,11 +937,11 @@ db.SubmitChanges() The entity to be attached. Attaches an entity to the in an unmodified state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -975,11 +975,11 @@ db.SubmitChanges() to attach the entity as modified; to attached the entity as unmodified. Attaches all entities of a collection to the in either a modified or unmodified state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1012,11 +1012,11 @@ db.SubmitChanges() An instance of the same entity type with data members that contain the original values. Attaches an entity to the in either a modified or unmodified state by specifying both the entity and its original state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1056,11 +1056,11 @@ db.SubmitChanges() The collection of entities to be attached. Attaches all entities of a collection to the in either a modified or unmodified state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1094,11 +1094,11 @@ db.SubmitChanges() to attach the entities as modified; to attach the entities as unmodified. Attaches all entities of a collection to the in either a modified or unmodified state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1129,11 +1129,11 @@ db.SubmitChanges() The entities being removed. Puts all entities from the collection into a state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1164,14 +1164,14 @@ db.SubmitChanges() The entity to be removed. Puts an entity from this table into a state. - instance is cast to an interface. - + instance is cast to an interface. + > [!NOTE] -> LINQ to SQL does not support or recognize cascade-delete operations. If you want to delete a row in a table that has constraints against it, you must either set the `ON DELETE CASCADE` rule in the foreign-key constraint in the database, or use your own code to first delete the child objects that prevent the parent object from being deleted. Otherwise, an exception is thrown. - +> LINQ to SQL does not support or recognize cascade-delete operations. If you want to delete a row in a table that has constraints against it, you must either set the `ON DELETE CASCADE` rule in the foreign-key constraint in the database, or use your own code to first delete the child objects that prevent the parent object from being deleted. Otherwise, an exception is thrown. + ]]> @@ -1203,11 +1203,11 @@ db.SubmitChanges() Returns an array of modified members that contain their current and original values. An array of modified members. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1239,11 +1239,11 @@ db.SubmitChanges() Retrieves original values of a given entity. A copy of the original entity. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1274,11 +1274,11 @@ db.SubmitChanges() The collection of entities to be added. Adds all entities of a collection to the in an state. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1309,11 +1309,11 @@ db.SubmitChanges() The entity to add. Adds an entity in a state to this table. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1341,11 +1341,11 @@ db.SubmitChanges() Gets the type of the element(s) that are returned when the expression tree associated with this object is executed. The type of the element(s) that are returned when the expression tree associated with this object is executed. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1373,11 +1373,11 @@ db.SubmitChanges() Gets the expression tree that is associated with this instance of . The that is associated with this instance of . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1405,11 +1405,11 @@ db.SubmitChanges() Gets the query provider that is associated with this data source. The that is associated with this data source. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1441,11 +1441,11 @@ db.SubmitChanges() Constructs an object that can evaluate the query represented by a specified expression tree. An that can evaluate the query represented by the specified expression tree. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1481,11 +1481,11 @@ db.SubmitChanges() Constructs an object that can evaluate the query represented by a specified expression tree. An that can evaluate the query represented by the specified expression tree. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1517,11 +1517,11 @@ db.SubmitChanges() Executes the query represented by a specified expression tree. The value that results from executing the specified query. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1557,11 +1557,11 @@ db.SubmitChanges() Executes the strongly-typed query represented by a specified expression tree. The value that results from executing the specified query. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data.Metadata.Edm/Facet.xml b/xml/System.Data.Metadata.Edm/Facet.xml index 82be024e251..fd2c6f99d7f 100644 --- a/xml/System.Data.Metadata.Edm/Facet.xml +++ b/xml/System.Data.Metadata.Edm/Facet.xml @@ -23,7 +23,7 @@ Provides additional information about members. In the ADO.NET metadata type hierarchy, facets provide additional information about members through the declared type for the member. - if the value of the facet is unbounded; otherwise, . - indicates that the value of the property can have the maximum allowable limit in the underlying storage. - + indicates that the value of the property can have the maximum allowable limit in the underlying storage. + ]]> diff --git a/xml/System.Data.Metadata.Edm/MetadataProperty.xml b/xml/System.Data.Metadata.Edm/MetadataProperty.xml index 6091b8b59b9..f07270edadd 100644 --- a/xml/System.Data.Metadata.Edm/MetadataProperty.xml +++ b/xml/System.Data.Metadata.Edm/MetadataProperty.xml @@ -20,7 +20,7 @@ class provides properties called , , and so on. The class also inherits a property, which is a collection of objects. When the application creates an instance of the class, the property automatically contains a collection of objects for property, property, and so on. + You can access every item in the ADO.NET metadata hierarchy as a strongly typed property bag. The class provides properties called , , and so on. The class also inherits a property, which is a collection of objects. When the application creates an instance of the class, the property automatically contains a collection of objects for property, property, and so on. ]]> diff --git a/xml/System.Data.Metadata.Edm/NavigationProperty.xml b/xml/System.Data.Metadata.Edm/NavigationProperty.xml index 4fa9f728103..6b2cfadf042 100644 --- a/xml/System.Data.Metadata.Edm/NavigationProperty.xml +++ b/xml/System.Data.Metadata.Edm/NavigationProperty.xml @@ -17,11 +17,11 @@ Represents the navigation from one entity type to another entity type in the conceptual model . - in a conceptual model, see [NavigationProperty element (CSDL)](/ef/ef6/modeling/designer/advanced/edmx/csdl-spec#navigationproperty-element-csdl). - + ]]> @@ -100,13 +100,13 @@ Gets the foreign key properties for a navigation property that is on the dependent end of a referential constraint. A collection of the foreign key properties. - method returns the corresponding foreign key properties. The returned properties will be in the same order as the principal end key properties. - - If the navigation property is not on the dependent end of a referential constraint, the method returns an empty collection. - + method returns the corresponding foreign key properties. The returned properties will be in the same order as the principal end key properties. + + If the navigation property is not on the dependent end of a referential constraint, the method returns an empty collection. + ]]> diff --git a/xml/System.Data.Metadata.Edm/PrimitiveType.xml b/xml/System.Data.Metadata.Edm/PrimitiveType.xml index fa659633853..038da3b6001 100644 --- a/xml/System.Data.Metadata.Edm/PrimitiveType.xml +++ b/xml/System.Data.Metadata.Edm/PrimitiveType.xml @@ -115,13 +115,13 @@ Returns the equivalent of this . An object that is an equivalent of this . - returns the model equivalent type for this type, For example, if this instance is `nvarchar` and its base type is a conceptual model string, then the return type is a conceptual model string. - - If the type is actually already a model type, then the return type is "this". - + returns the model equivalent type for this type, For example, if this instance is `nvarchar` and its base type is a conceptual model string, then the return type is a conceptual model string. + + If the type is actually already a model type, then the return type is "this". + ]]> @@ -150,11 +150,11 @@ Returns the equivalent of a . An object that is an equivalent of a specified . - . - + . + ]]> diff --git a/xml/System.Data.Objects.DataClasses/ComplexObject.xml b/xml/System.Data.Objects.DataClasses/ComplexObject.xml index 073e286ade7..f631393aeb6 100644 --- a/xml/System.Data.Objects.DataClasses/ComplexObject.xml +++ b/xml/System.Data.Objects.DataClasses/ComplexObject.xml @@ -103,11 +103,11 @@ method is called after a property change to commit the cached value in the as the original value of the property. + When a complex type is generated by the Entity Data Model tools, the method is called after a property change to commit the cached value in the as the original value of the property. - This method calls the method in the change tracker. + This method calls the method in the change tracker. - When tracking changes that are made to the property of a custom complex object, you must call . Do this when the complex object inherits from . + When tracking changes that are made to the property of a custom complex object, you must call . Do this when the complex object inherits from . ]]> @@ -141,11 +141,11 @@ method is called before a property change to cache the current value of the property in the so that this value can be used as the original value for the property. + When a complex type is generated by the Entity Data Model tools, the method is called before a property change to cache the current value of the property in the so that this value can be used as the original value for the property. - This method calls the method in the change tracker. + This method calls the method in the change tracker. - When tracking changes that are made to the property of a custom complex object, you must call . Do this when the complex object inherits from . + When tracking changes that are made to the property of a custom complex object, you must call . Do this when the complex object inherits from . ]]> diff --git a/xml/System.Data.Objects.DataClasses/EdmRelationshipNavigationPropertyAttribute.xml b/xml/System.Data.Objects.DataClasses/EdmRelationshipNavigationPropertyAttribute.xml index d0605bff1f4..17d26538ba0 100644 --- a/xml/System.Data.Objects.DataClasses/EdmRelationshipNavigationPropertyAttribute.xml +++ b/xml/System.Data.Objects.DataClasses/EdmRelationshipNavigationPropertyAttribute.xml @@ -30,9 +30,9 @@ This attribute is applied to the following types of navigation properties: -- Properties that return an of related objects. +- Properties that return an of related objects. -- Properties that return the value of the of a related object, as in the following example from the `SalesOrderDetail` type. +- Properties that return the value of the of a related object, as in the following example from the `SalesOrderDetail` type. diff --git a/xml/System.Data.Objects.DataClasses/EdmScalarPropertyAttribute.xml b/xml/System.Data.Objects.DataClasses/EdmScalarPropertyAttribute.xml index dc3837a7af4..32f99738260 100644 --- a/xml/System.Data.Objects.DataClasses/EdmScalarPropertyAttribute.xml +++ b/xml/System.Data.Objects.DataClasses/EdmScalarPropertyAttribute.xml @@ -23,15 +23,15 @@ Attribute that indicates that the property represents a scalar property. - and properties cannot both be `true` because key members cannot be `null`. - - The links a scalar property on a data class to a property of an entity type or complex type that is defined in the conceptual model. - - This attribute is applied to properties that return scalar types. - + and properties cannot both be `true` because key members cannot be `null`. + + The links a scalar property on a data class to a property of an entity type or complex type that is defined in the conceptual model. + + This attribute is applied to properties that return scalar types. + ]]> @@ -84,13 +84,13 @@ Gets or sets the value that indicates whether the property is part of the entity key. The value that indicates whether the property is part of the entity key. - can be set to true for more than one property of an entity type. - - The and properties cannot both be `true` because key members cannot be `null`. - + can be set to true for more than one property of an entity type. + + The and properties cannot both be `true` because key members cannot be `null`. + ]]> @@ -125,11 +125,11 @@ Gets or sets the value that indicates whether the property can have a value. The value that indicates whether the property can have a value. - and properties cannot both be `true`. - + and properties cannot both be `true`. + ]]> diff --git a/xml/System.Data.Objects.DataClasses/EdmSchemaAttribute.xml b/xml/System.Data.Objects.DataClasses/EdmSchemaAttribute.xml index 3b05b8e521c..3a8960fd468 100644 --- a/xml/System.Data.Objects.DataClasses/EdmSchemaAttribute.xml +++ b/xml/System.Data.Objects.DataClasses/EdmSchemaAttribute.xml @@ -23,11 +23,11 @@ Attribute that indicates that the assembly contains classes that are mapped to entity types in a conceptual model. - constructor must be used to supply a GUID string value that is unique for each conceptual model referenced by the assembly. - + constructor must be used to supply a GUID string value that is unique for each conceptual model referenced by the assembly. + ]]> CSDL Specification @@ -88,11 +88,11 @@ A string that is a unique GUID value for the model in the assembly. Initializes a new instance of the class with a unique value for each model referenced by the assembly. - is applied multiple times to a single assembly in a Visual Basic project. - + is applied multiple times to a single assembly in a Visual Basic project. + ]]> CSDL Specification diff --git a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml index 2c6068d1de7..0ba8d3b1516 100644 --- a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml +++ b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml @@ -55,11 +55,11 @@ is a collection of objects of a particular entity type that represents the "many" end of a one-to-many or many-to-many relationship. + An is a collection of objects of a particular entity type that represents the "many" end of a one-to-many or many-to-many relationship. - An is returned by a navigation property. Use the method to load related objects into an . To store an unrelated collection of objects of a specific entity type, such as the result of an , use an instance of the class. + An is returned by a navigation property. Use the method to load related objects into an . To store an unrelated collection of objects of a specific entity type, such as the result of an , use an instance of the class. - An might have a corresponding . When an and an model opposite ends of the same relationship, the integrity of the relationship is maintained at the object level. The two classes are synchronized automatically. + An might have a corresponding . When an and an model opposite ends of the same relationship, the integrity of the relationship is maintained at the object level. The two classes are synchronized automatically. This class cannot be inherited. @@ -74,13 +74,13 @@ 3. Iterates through the collection of s. -4. Gets the for each related end. +4. Gets the for each related end. -5. Uses the method to remove one of the entities from the collection. +5. Uses the method to remove one of the entities from the collection. -6. Calls the method to determine whether the object was removed from the collection. +6. Calls the method to determine whether the object was removed from the collection. -7. Uses the method to add the entity back. +7. Uses the method to add the entity back. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetirelatedend_add"::: @@ -113,9 +113,9 @@ is intended to be used by Object Services when deserializing object graphs. You should access an instance of from a navigation property instead of using this constructor. + This public constructor for is intended to be used by Object Services when deserializing object graphs. You should access an instance of from a navigation property instead of using this constructor. - To store an unrelated collection of objects of a specific entity type, such as the result of an , use an instance of . + To store an unrelated collection of objects of a specific entity type, such as the result of an , use an instance of . ]]> @@ -150,14 +150,14 @@ method adds an object to an and creates a relationship between the two objects. When the source object is attached to an instance, the method also adds the object to the . This operation is translated into an insert operation in the data source when is called. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). + The method adds an object to an and creates a relationship between the two objects. When the source object is attached to an instance, the method also adds the object to the . This operation is translated into an insert operation in the data source when is called. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). - The method can be called multiple times on the same object instance. + The method can be called multiple times on the same object instance. ## Examples This example is based on the Adventure Works Sales Model. To run the code in this example, you must have already added the AdventureWorks Sales Model to your project and configured your project to use the Entity Framework. To do this, complete the procedures in [How to: Manually Configure an Entity Framework Project](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738546(v=vs.100)) and [How to: Manually Define the Model and Mapping Files](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399785(v=vs.100)). - This example creates two new `SalesOrderHeader` entities, adds them to the `Contact` entity, and, after removing an object, uses the method to add the object back to the collection. + This example creates two new `SalesOrderHeader` entities, adds them to the `Contact` entity, and, after removing an object, uses the method to add the object back to the collection. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetirelatedend_add"::: @@ -203,9 +203,9 @@ method is used to define relationships between an object and a collection of related objects when both the source object and the collection of related objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the method on the . To create a new object that is related to the source object, call the method on the . For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The method is used to define relationships between an object and a collection of related objects when both the source object and the collection of related objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the method on the . To create a new object that is related to the source object, call the method on the . For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). - If the collection is already filled or partially filled, the method merges existing entities with the given entities. The given entities are not assumed to be the complete set of related entities. + If the collection is already filled or partially filled, the method merges existing entities with the given entities. The given entities are not assumed to be the complete set of related entities. All entities passed in must be in the or state. Objects in the state are only allowed when the state manager is already tracking the relationship instance. @@ -246,13 +246,13 @@ method is used to define relationships between two objects when both objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the method on the . To create a new object that is related to the source object, call the method on the . For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The method is used to define relationships between two objects when both objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the method on the . To create a new object that is related to the source object, call the method on the . For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). - If the already has loaded objects, the method merges the object together with the existing objects in the . + If the already has loaded objects, the method merges the object together with the existing objects in the . The attached object is not assumed to be the complete set of related entity objects. - The object associated with this and all objects being attached to it must be in an or state. + The object associated with this and all objects being attached to it must be in an or state. Objects in the state can only be attached when the is already tracking the relationship instance. @@ -301,15 +301,15 @@ does the following: + does the following: -- Sets the flag to `false`. +- Sets the flag to `false`. - Removes all entities from the collection. -- Detaches relationships between removed entities and the owner of the from the . +- Detaches relationships between removed entities and the owner of the from the . -- Removes the owner of the from the related entities. +- Removes the owner of the from the related entities. ]]> @@ -346,7 +346,7 @@ method to compare the specified object with the objects already in the collection. + Uses the method to compare the specified object with the objects already in the collection. @@ -361,13 +361,13 @@ 3. Iterates through the collection of s. -4. Gets the for each related end. +4. Gets the for each related end. -5. Uses the method to remove one of the entities from the collection. +5. Uses the method to remove one of the entities from the collection. -6. Calls the method to determine whether the object was removed from the collection. +6. Calls the method to determine whether the object was removed from the collection. -7. Uses the method to add the entity back. +7. Uses the method to add the entity back. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetirelatedend_add"::: @@ -432,7 +432,7 @@ property gets the number of entities currently in the local collection and does not reflect the size of the collection in the data source. A count of zero does not necessarily indicate that the related collection is empty. To determine the collection size in the data source, call the method or include the related object in the query path. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). + The property gets the number of entities currently in the local collection and does not reflect the size of the collection in the data source. A count of zero does not necessarily indicate that the related collection is empty. To determine the collection size in the data source, call the method or include the related object in the query path. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). ]]> @@ -463,16 +463,16 @@ that returns the same set of objects. This is useful as the starting point for a more complex join, union, or filtered query, or to return the same objects in a detached state by using the option. + This property is used to obtain a new instance of that returns the same set of objects. This is useful as the starting point for a more complex join, union, or filtered query, or to return the same objects in a detached state by using the option. - is used to filter objects in an to enable you to bind only objects of a specific type. For more information, see [Binding Objects to Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738469(v=vs.100)). + is used to filter objects in an to enable you to bind only objects of a specific type. For more information, see [Binding Objects to Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738469(v=vs.100)). ## Examples This example is based on a modified version of the [School Model](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896300(v=vs.100)). This version supports table-per-type inheritance with `Course` as an abstract type. Complete the walkthrough to modify the School model to support the table-per-type inheritance example used in this topic. - This example shows how to use to filter objects in an and bind only to objects of a specific type. For a complete version of this example, see [How to: Bind Controls to Derived Types](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283135(v=vs.100)). + This example shows how to use to filter objects in an and bind only to objects of a specific type. For a complete version of this example, see [How to: Bind Controls to Derived Types](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283135(v=vs.100)). @@ -564,23 +564,23 @@ has the correct conditions. The `RelatedEnd.ValidateLoad` method checks that: +This method calls the internal `RelatedEnd.ValidateLoad` method before loading the collection, which validates that a call to has the correct conditions. The `RelatedEnd.ValidateLoad` method checks that: * A valid exists. * The entity isn't in a state. -* for must be if and only if the source entity was . If the source entity was retrieved with any other , the can be anything but (for example, the entity could have been loaded with and the option can be ). -* If `mergeOption` is , isn't called on an already loaded entity and isn't called on a non-empty, not-tracked . +* for must be if and only if the source entity was . If the source entity was retrieved with any other , the can be anything but (for example, the entity could have been loaded with and the option can be ). +* If `mergeOption` is , isn't called on an already loaded entity and isn't called on a non-empty, not-tracked . - When objects in the collection are already loaded into the , the method enforces the specified by the `mergeOption` parameter. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)). + When objects in the collection are already loaded into the , the method enforces the specified by the `mergeOption` parameter. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)). - To explicitly load related objects, you must call the `Load` method on the related end returned by the navigation property. For a one-to-many relationship, call the method on . For a one-to-one relationship, call the on . This loads the related object data into the object context. You can enumerate through the collection of returned results using a `foreach` loop (`For Each...Next` in Visual Basic) and conditionally call the `Load` method on and properties for each entity in the results. + To explicitly load related objects, you must call the `Load` method on the related end returned by the navigation property. For a one-to-many relationship, call the method on . For a one-to-one relationship, call the on . This loads the related object data into the object context. You can enumerate through the collection of returned results using a `foreach` loop (`For Each...Next` in Visual Basic) and conditionally call the `Load` method on and properties for each entity in the results. - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. > [!NOTE] -> When you call the method during a `foreach` (C#) or `For Each` (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying `multipleactiveresultsets=true` in the connection string. You can also load the result of the query into a collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects. +> When you call the method during a `foreach` (C#) or `For Each` (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying `multipleactiveresultsets=true` in the connection string. You can also load the result of the query into a collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects. - The method is synchronized with the method. + The method is synchronized with the method. @@ -702,16 +702,16 @@ This method calls the internal `RelatedEnd.ValidateLoad` method before loading t method also deletes the relationship between the source object and the object being removed from the collection. If the relationship has a referential integrity constraint, calling the method on a dependent object marks both the relationship and the dependent object for deletion. This occurs because the constraint indicates that the dependent object cannot exist without a relationship to the parent. For more information, see [ReferentialConstraint Element (CSDL)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738464(v=vs.100)). + The method also deletes the relationship between the source object and the object being removed from the collection. If the relationship has a referential integrity constraint, calling the method on a dependent object marks both the relationship and the dependent object for deletion. This occurs because the constraint indicates that the dependent object cannot exist without a relationship to the parent. For more information, see [ReferentialConstraint Element (CSDL)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738464(v=vs.100)). - returns `false` when the specified object is not in the collection. + returns `false` when the specified object is not in the collection. ## Examples This example is based on the Adventure Works Sales Model. To run the code in this example, you must have already added the AdventureWorks Sales Model to your project and configured your project to use the Entity Framework. To do this, complete the procedures in [How to: Manually Configure an Entity Framework Project](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738546(v=vs.100)) and [How to: Manually Define the Model and Mapping Files](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399785(v=vs.100)). - This example uses the method to remove one of the entities from the collection and then calls the method to determine whether the object was removed from the collection. + This example uses the method to remove one of the entities from the collection and then calls the method to determine whether the object was removed from the collection. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetirelatedend_add"::: @@ -786,7 +786,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -819,9 +819,9 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - This method enables data binding to an . It is called by the control bound to the collection. For more information, see [Binding Objects to Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738469(v=vs.100)). + This method enables data binding to an . It is called by the control bound to the collection. For more information, see [Binding Objects to Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738469(v=vs.100)). ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityObject.xml b/xml/System.Data.Objects.DataClasses/EntityObject.xml index 91686b1fcff..3eda7336498 100644 --- a/xml/System.Data.Objects.DataClasses/EntityObject.xml +++ b/xml/System.Data.Objects.DataClasses/EntityObject.xml @@ -140,7 +140,7 @@ , the becomes . + When an object is attached to the object context, either as the result of a query or by calling , the becomes . When an object is detached from the object context, it returns to the state. @@ -175,9 +175,9 @@ method is called after a property change to commit the cached value in the as the original value of the property. + When an entity type is generated by the Entity Data Model tools, the method is called after a property change to commit the cached value in the as the original value of the property. - This method calls the method in the change tracker. + This method calls the method in the change tracker. ]]> @@ -212,9 +212,9 @@ method is called before a property change to cache the current value of the property in the so that this value can be used as the original value for the property. + When an entity type is generated by the Entity Data Model tools, the method is called before a property change to cache the current value of the property in the so that this value can be used as the original value for the property. - This method calls the method in the change tracker. + This method calls the method in the change tracker. ]]> @@ -285,9 +285,9 @@ returns a used by this object. Object Services uses the relationship manager to provide access to related objects. + returns a used by this object. Object Services uses the relationship manager to provide access to related objects. - Classes that expose relationships must implement this property by constructing and setting in their constructor. The implementation of this property should use the static method to create a new when needed. After being created, it is expected that this object will be stored on the entity and will be provided through this property. + Classes that expose relationships must implement this property by constructing and setting in their constructor. The implementation of this property should use the static method to create a new when needed. After being created, it is expected that this object will be stored on the entity and will be provided through this property. ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityReference.xml b/xml/System.Data.Objects.DataClasses/EntityReference.xml index c2bb011d276..ddf87ab4cc9 100644 --- a/xml/System.Data.Objects.DataClasses/EntityReference.xml +++ b/xml/System.Data.Objects.DataClasses/EntityReference.xml @@ -27,11 +27,11 @@ Base class that implements non-generic functionality for an . - class exposes the of the related object and is a base class for the class. An object is returned by a navigation property when the related end has a multiplicity of zero or one. For more information, see [NavigationProperty Element (CSDL)](https://msdn.microsoft.com/library/5829a238-a50e-4c81-901d-7b54fc00f27e). - + class exposes the of the related object and is a base class for the class. An object is returned by a navigation property when the related end has a multiplicity of zero or one. For more information, see [NavigationProperty Element (CSDL)](https://msdn.microsoft.com/library/5829a238-a50e-4c81-901d-7b54fc00f27e). + ]]> @@ -79,13 +79,13 @@ Returns the key for the related object. An that is the key of the related object. - object makes it easier to return information about the related object without having to load it from the data source. - - Exposing the of the related object on the object also enables Object Service to dynamically create an association between two attached objects and delete an object without having to load the related ends. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). - + object makes it easier to return information about the related object without having to load it from the data source. + + Exposing the of the related object on the object also enables Object Service to dynamically create an association between two attached objects and delete an object without having to load the related ends. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). + ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityReference`1.xml b/xml/System.Data.Objects.DataClasses/EntityReference`1.xml index 0a7d463f984..642f4bec3a8 100644 --- a/xml/System.Data.Objects.DataClasses/EntityReference`1.xml +++ b/xml/System.Data.Objects.DataClasses/EntityReference`1.xml @@ -43,16 +43,16 @@ object is returned by a navigation property when the related end has a multiplicity of zero or one. For more information, see [NavigationProperty Element (CSDL)](https://msdn.microsoft.com/library/5829a238-a50e-4c81-901d-7b54fc00f27e). + An object is returned by a navigation property when the related end has a multiplicity of zero or one. For more information, see [NavigationProperty Element (CSDL)](https://msdn.microsoft.com/library/5829a238-a50e-4c81-901d-7b54fc00f27e). - An object might have a corresponding (one-to-many relationship) or (one-to-one relationship) at the other end of the relationship. When an and an model opposing ends of the same relationship, the integrity of the relationship is maintained at the object level. + An object might have a corresponding (one-to-many relationship) or (one-to-one relationship) at the other end of the relationship. When an and an model opposing ends of the same relationship, the integrity of the relationship is maintained at the object level. This class cannot be inherited. ## Examples - This example shows how to use the object to change a relationship between a `SalesOrderHeader` object and a related `Address` object that represents the shipping address for the order. + This example shows how to use the object to change a relationship between a `SalesOrderHeader` object and a related `Address` object that represents the shipping address for the order. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetchangeobjectrelationship"::: @@ -104,9 +104,9 @@ method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). - The object associated with this and all objects being attached to it must be in an or state. + The object associated with this and all objects being attached to it must be in an or state. An object in the state can only be attached when the is already tracking the relationship instance. @@ -141,7 +141,7 @@ that, when it is executed, returns the related object. This is useful as the starting point for a more complex join, union, or filtered query, or to return the referenced object in a detached state using the option. + This method is used to obtain a new instance of that, when it is executed, returns the related object. This is useful as the starting point for a more complex join, union, or filtered query, or to return the referenced object in a detached state using the option. ]]> @@ -180,23 +180,23 @@ ## Remarks This method is used to load the related object. - When loaded, the related object is accessed from the property. + When loaded, the related object is accessed from the property. - To explicitly load related objects, you must call the `Load` method on the related end returned by the navigation property. For a one-to-many relationship, call the method on , and for a one-to-one relationship, call the on . This loads the related object data into the object context. When a query returns results, you can enumerate through the collection of objects using a `foreach` loop (`For Each...Next` in Visual Basic) and conditionally call the `Load` method on and properties for each entity in the results. + To explicitly load related objects, you must call the `Load` method on the related end returned by the navigation property. For a one-to-many relationship, call the method on , and for a one-to-one relationship, call the on . This loads the related object data into the object context. When a query returns results, you can enumerate through the collection of objects using a `foreach` loop (`For Each...Next` in Visual Basic) and conditionally call the `Load` method on and properties for each entity in the results. - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. > [!NOTE] -> When you call the method during a `foreach` (C#) or `For Each` (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying `multipleactiveresultsets=true` in the connection string. You can also load the result of the query into a collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects. +> When you call the method during a `foreach` (C#) or `For Each` (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying `multipleactiveresultsets=true` in the connection string. You can also load the result of the query into a collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects. -This method calls the internal `RelatedEnd.ValidateLoad` method before loading the related object, which validates that a call to has the correct conditions. The `RelatedEnd.ValidateLoad` method checks that: +This method calls the internal `RelatedEnd.ValidateLoad` method before loading the related object, which validates that a call to has the correct conditions. The `RelatedEnd.ValidateLoad` method checks that: * A valid exists. * The entity isn't in a state. -* for must be if and only if the source entity was . If the source entity was retrieved with any other , the can be anything but (for example, the entity could have been loaded with and the option can be ). -* If `mergeOption` is , isn't called on an already loaded entity and isn't called on a non-empty, not-tracked . +* for must be if and only if the source entity was . If the source entity was retrieved with any other , the can be anything but (for example, the entity could have been loaded with and the option can be ). +* If `mergeOption` is , isn't called on an already loaded entity and isn't called on a non-empty, not-tracked . - When the related object is already loaded in the , the method enforces the specified by the `mergeOption` parameter. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)). + When the related object is already loaded in the , the method enforces the specified by the `mergeOption` parameter. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)). ]]> diff --git a/xml/System.Data.Objects.DataClasses/IEntityChangeTracker.xml b/xml/System.Data.Objects.DataClasses/IEntityChangeTracker.xml index d5db9d12752..4ee2e4e0942 100644 --- a/xml/System.Data.Objects.DataClasses/IEntityChangeTracker.xml +++ b/xml/System.Data.Objects.DataClasses/IEntityChangeTracker.xml @@ -55,7 +55,7 @@ is used by to report that a property has changed. + is used by to report that a property has changed. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). @@ -93,7 +93,7 @@ is used by and to report that a complex property is changing. + is used by and to report that a complex property is changing. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). @@ -127,7 +127,7 @@ is used by to report that a property has changed. + is used by to report that a property has changed. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). @@ -161,7 +161,7 @@ is used by to report that a property is changing. + is used by to report that a property is changing. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). diff --git a/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml b/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml index 4dcaca8486c..6696b163c3f 100644 --- a/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml +++ b/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml @@ -17,7 +17,7 @@ defines the requirements for an object that represents an end in an association. This interface is implemented by the class. is the base class for the and classes. + defines the requirements for an object that represents an end in an association. This interface is implemented by the class. is the base class for the and classes. ## Examples @@ -64,13 +64,13 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti method adds an object to the related end. The related end must be an . + The method adds an object to the related end. The related end must be an . When the source object implements and is being tracked in the , the object being added is also tracked. - The class explicitly implements the method. The class uses this implementation. For more information, see . + The class explicitly implements the method. The class uses this implementation. For more information, see . - If the related end is an and the property of the reference is not `null`, this method throws an exception. + If the related end is an and the property of the reference is not `null`, this method throws an exception. ]]> @@ -101,13 +101,13 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti . Use the method for entity classes that do implement . + Use this method overload for entity classes that do not implement . Use the method for entity classes that do implement . - The method adds an object to the related end. The related end must be an . + The method adds an object to the related end. The related end must be an . - The class explicitly implements the method. The class uses this implementation. For more information, see . + The class explicitly implements the method. The class uses this implementation. For more information, see . - If the related end is an and the property of the reference is not `null`, this method throws an exception. + If the related end is an and the property of the reference is not `null`, this method throws an exception. ]]> @@ -148,9 +148,9 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti method is used to define a relationship between two objects that are both attached to the same instance. + The method is used to define a relationship between two objects that are both attached to the same instance. - The class explicitly implements the method. The class uses this implementation to define relationships between the attached source object and the object attached to the collection. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The class explicitly implements the method. The class uses this implementation to define relationships between the attached source object and the object attached to the collection. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). ]]> @@ -181,11 +181,11 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti . Use the method for entity classes that do implement . + Use this method overload for entity classes that do not implement . Use the method for entity classes that do implement . - The method is used to define a relationship between two objects that are both attached to the same instance. + The method is used to define a relationship between two objects that are both attached to the same instance. - The class explicitly implements the method. The class uses this implementation to define relationships between the attached source object and the object attached to the collection. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The class explicitly implements the method. The class uses this implementation to define relationships between the attached source object and the object attached to the collection. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). ]]> @@ -215,7 +215,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti method is explicitly implemented by the class. The and classes both override the method to return an that, when it is executed, returns the same set of objects that belong to the related end. + The method is explicitly implemented by the class. The and classes both override the method to return an that, when it is executed, returns the same set of objects that belong to the related end. ]]> @@ -268,9 +268,9 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the method of . For more information, see . + The class implements the method of . For more information, see . - The and classes inherit from . + The and classes inherit from . @@ -321,11 +321,11 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the method of . For more information, see . + The class implements the method of . For more information, see . - is called to explicitly load related objects from a related end exposed by a navigation property. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). + is called to explicitly load related objects from a related end exposed by a navigation property. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. ]]> @@ -357,11 +357,11 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the method. Both the and classes override this implementation. + The class implements the method. Both the and classes override this implementation. `Load` is called to explicitly load related objects from a related end that is exposed by a navigation property. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. ]]> @@ -458,9 +458,9 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti method removes an object from the related end. The related end must be an . + The method removes an object from the related end. The related end must be an . - The class explicitly implements the method. The class uses this implementation. For more information, see . + The class explicitly implements the method. The class uses this implementation. For more information, see . ]]> @@ -493,11 +493,11 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti . Use the method for entity classes that do implement . + Use this method overload for entity classes that do not implement . Use the method for entity classes that do implement . - The method removes an object from the related end. The related end must be an . + The method removes an object from the related end. The related end must be an . - The class explicitly implements the method. The class uses this implementation. For more information, see . + The class explicitly implements the method. The class uses this implementation. For more information, see . ]]> @@ -526,7 +526,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the property. For more information, see . + The class implements the property. For more information, see . The role name is specified by the `Role` attribute of the `End` element in the association that defines this relationship in the conceptual model. For more information, see [Association Element (CSDL)](https://msdn.microsoft.com/library/c305169a-8af7-432f-9ba7-800a163aed41). @@ -557,7 +557,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the property. For more information, see . + The class implements the property. For more information, see . The role name is specified by the `Role` attribute of the `End` element in the association that defines this relationship in the conceptual model. For more information, see [Association Element (CSDL)](https://msdn.microsoft.com/library/c305169a-8af7-432f-9ba7-800a163aed41). diff --git a/xml/System.Data.Objects.DataClasses/RelatedEnd.xml b/xml/System.Data.Objects.DataClasses/RelatedEnd.xml index 75f255b5ff7..e631132f3ed 100644 --- a/xml/System.Data.Objects.DataClasses/RelatedEnd.xml +++ b/xml/System.Data.Objects.DataClasses/RelatedEnd.xml @@ -34,9 +34,9 @@ is the base class for the class and the class. + is the base class for the class and the class. - The class implements functionality that is shared between the and classes. + The class implements functionality that is shared between the and classes. This class is not intended to be used directly in your code. @@ -68,19 +68,19 @@ ## Remarks The event is raised by the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - Events may be suppressed during bulk operations, such as `Load`, , and . + Events may be suppressed during bulk operations, such as `Load`, , and . ]]> @@ -117,7 +117,7 @@ (IEnumerable, Boolean)` method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property of the or call the method on the if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property of the or by calling the method on the and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896271(v=vs.100)). +The `Attach(IEnumerable, Boolean)` method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property of the or call the method on the if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property of the or by calling the method on the and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896271(v=vs.100)). The `Attach(IEnumerable, Boolean)` method is called by Object Services during attach operations against a related end. @@ -188,17 +188,17 @@ The `Attach(IEnumerable, Boolean)` method is called by Object method sets the flag to `true`. + Calling the method sets the flag to `true`. - Calling the method on an sets to `false`. + Calling the method on an sets to `false`. - An or may also be loaded if the related end is included in the query path. For more information about span, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). + An or may also be loaded if the related end is included in the query path. For more information about span, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). - The `Load` method on and loads related objects from the data source whether or not is `true`. + The `Load` method on and loads related objects from the data source whether or not is `true`. - When an object is detached, the flag is changed from `false` to `true`. + When an object is detached, the flag is changed from `false` to `true`. - To guarantee that a related end is fully loaded before doing processing, you should check whether is `false`. If is `false`, you should call the method. + To guarantee that a related end is fully loaded before doing processing, you should check whether is `false`. If is `false`, you should call the method. ]]> @@ -239,11 +239,11 @@ The `Attach(IEnumerable, Boolean)` method is called by Object for tracked objects or when the object is not tracked in the . To specify a merge option other than , call the `Load` method on the or the that takes a specific parameter. + The default merge option is for tracked objects or when the object is not tracked in the . To specify a merge option other than , call the `Load` method on the or the that takes a specific parameter. - Calling the method sets the flag to `true`. + Calling the method sets the flag to `true`. - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. ]]> @@ -287,11 +287,11 @@ The `Attach(IEnumerable, Boolean)` method is called by Object and override this method to load related objects. `Load` is called to explicitly load related objects from a related end exposed by a navigation property. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). + Both and override this method to load related objects. `Load` is called to explicitly load related objects from a related end exposed by a navigation property. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). - Calling the method sets the flag to `true`. + Calling the method sets the flag to `true`. - The method loads related objects from the data source whether or not is `true`. + The method loads related objects from the data source whether or not is `true`. The default merge option is for tracked objects or when the object is not tracked in the . @@ -544,7 +544,7 @@ The `Merge` method is called by Object Services during relationship ope ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - The method is only maintained for compatibility with previous versions of the .NET Framework. + The method is only maintained for compatibility with previous versions of the .NET Framework. ]]> @@ -624,7 +624,7 @@ The `Merge` method is called by Object Services during relationship ope ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - The method is only maintained for compatibility with previous versions of the .NET Framework. + The method is only maintained for compatibility with previous versions of the .NET Framework. ]]> @@ -695,7 +695,7 @@ The `Merge` method is called by Object Services during relationship ope ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - and both override to return an . This query, when it is executed, returns the same set of objects that belong to the related end. + and both override to return an . This query, when it is executed, returns the same set of objects that belong to the related end. ]]> @@ -742,7 +742,7 @@ The `Merge` method is called by Object Services during relationship ope ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - The method is only maintained for compatibility with previous versions of the .NET Framework. + The method is only maintained for compatibility with previous versions of the .NET Framework. ]]> @@ -916,7 +916,7 @@ The `ValidateEntityForAttach` method is called by Object Services durin by calling the [IRelatedEnd.CreateSourceQuery](xref:System.Data.Objects.DataClasses.RelatedEnd.System%23Data%23Objects%23DataClasses%23IRelatedEnd%23CreateSourceQuery) method. +Object Services obtains the by calling the [IRelatedEnd.CreateSourceQuery](xref:System.Data.Objects.DataClasses.RelatedEnd.System%23Data%23Objects%23DataClasses%23IRelatedEnd%23CreateSourceQuery) method. Object Services calls the `ValidateLoad` method before executing a load operation to ensure that the operation will succeed. diff --git a/xml/System.Data.Objects.DataClasses/RelationshipManager.xml b/xml/System.Data.Objects.DataClasses/RelationshipManager.xml index bb7d9c58adc..091932aa391 100644 --- a/xml/System.Data.Objects.DataClasses/RelationshipManager.xml +++ b/xml/System.Data.Objects.DataClasses/RelationshipManager.xml @@ -66,7 +66,7 @@ method is used by objects that implement . When Object Services requests the property of an object that implements , the method is called if the relationship manager does not already exist for the object. + The method is used by objects that implement . When Object Services requests the property of an object that implements , the method is called if the relationship manager does not already exist for the object. ]]> @@ -107,7 +107,7 @@ method returns an enumeration of and objects. and are concrete types that derive from . The abstract class implements the interface. + The method returns an enumeration of and objects. and are concrete types that derive from . The abstract class implements the interface. @@ -163,7 +163,7 @@ of related objects that have the specified relationship name and target role name. + Gets an of related objects that have the specified relationship name and target role name. The relationship name should not be namespace qualified. An error occurs when you prepend the namespace to the relationship name. @@ -323,9 +323,9 @@ method initializes an existing that was created by using the parameterless constructor. The is initialized by using the provided relationship and target role names. + The method initializes an existing that was created by using the parameterless constructor. The is initialized by using the provided relationship and target role names. - The method is used during deserialization only. + The method is used during deserialization only. ]]> @@ -394,9 +394,9 @@ method initializes an existing that was created by using the parameterless constructor. The is initialized by using the provided relationship and target role names. + The method initializes an existing that was created by using the parameterless constructor. The is initialized by using the provided relationship and target role names. - The method is used during deserialization only. + The method is used during deserialization only. ]]> diff --git a/xml/System.Data.Objects/CompiledQuery.xml b/xml/System.Data.Objects/CompiledQuery.xml index 6e93d70d983..ccfa9f40367 100644 --- a/xml/System.Data.Objects/CompiledQuery.xml +++ b/xml/System.Data.Objects/CompiledQuery.xml @@ -20,7 +20,7 @@ input parameter and other parameter values, produces some result (such as an instance). The query is translated and cached when the delegate is invoked for the first time. + Provides for compilation and caching of queries for reuse. Conceptually this class contains a single `Compile` method with several overloads. You call the `Compile` method to create a new delegate to represent the compiled query. The delegate, when invoked with the input parameter and other parameter values, produces some result (such as an instance). The query is translated and cached when the delegate is invoked for the first time. ## Examples The following example compiles and then invokes a query that accepts and input parameters and returns a sequence of orders where the order date is later than March 8, 2003 and the total due is less than $300.00: @@ -76,7 +76,7 @@ ## Examples - The following example compiles and then invokes a query that returns an instance: + The following example compiles and then invokes a query that returns an instance: :::code language="csharp" source="~/snippets/csharp/System.Data.Objects/CompiledQuery/Overview/Program.cs" id="Snippetcompiledquery1_mq"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DP L2E Conceptual Examples/VB/Module1.vb" id="Snippetcompiledquery1_mq"::: diff --git a/xml/System.Data.Objects/IObjectSet`1.xml b/xml/System.Data.Objects/IObjectSet`1.xml index 129c88d47f3..231c4f449b2 100644 --- a/xml/System.Data.Objects/IObjectSet`1.xml +++ b/xml/System.Data.Objects/IObjectSet`1.xml @@ -62,11 +62,11 @@ The new object to add to the set. Notifies the set that an object that represents a new entity must be added to the set. - . - + . + ]]> @@ -93,11 +93,11 @@ The existing object to add to the set. Notifies the set that an object that represents an existing entity must be added to the set. - . - + . + ]]> @@ -124,11 +124,11 @@ The existing object to delete from the set. Notifies the set that an object that represents an existing entity must be deleted from the set. - . - + . + ]]> @@ -155,11 +155,11 @@ The object to detach from the set. Notifies the set that an object that represents an existing entity must be detached from the set. - . - + . + ]]> diff --git a/xml/System.Data.Objects/MergeOption.xml b/xml/System.Data.Objects/MergeOption.xml index 7cc2b820772..805d648a5ed 100644 --- a/xml/System.Data.Objects/MergeOption.xml +++ b/xml/System.Data.Objects/MergeOption.xml @@ -30,7 +30,7 @@ If the state of the entity is . +Only modified properties are persisted to the data source when you call . ]]> diff --git a/xml/System.Data.Objects/ObjectContext.xml b/xml/System.Data.Objects/ObjectContext.xml index 3daadf26cd6..6d9cc240de3 100644 --- a/xml/System.Data.Objects/ObjectContext.xml +++ b/xml/System.Data.Objects/ObjectContext.xml @@ -218,7 +218,7 @@ This method iterates all the objects within the that are Added or Modified, and then sets the state of the entry to Unchanged. The Deleted items become detached. - If the method was called and the was not specified, the user must call the method. The method is useful in the scenario where a transaction has failed and a user wants to retry. + If the method was called and the was not specified, the user must call the method. The method is useful in the scenario where a transaction has failed and a user wants to retry. ]]> @@ -253,15 +253,15 @@ on the to add the object to the object context. Do this when the object is a new object that does not yet exist in the data source. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + Call on the to add the object to the object context. Do this when the object is a new object that does not yet exist in the data source. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). Objects are added to the in the , or state. When you create a new object that is related to another object in the object context, add the object by using one of the following methods: -- Call the method on the and specify the related object. Do this for a one-to-many or many-to-many relationship. +- Call the method on the and specify the related object. Do this for a one-to-many or many-to-many relationship. -- Set the property of the to the related object. Do this for a one-to-one or many-to-one relationship. +- Set the property of the to the related object. Do this for a one-to-one or many-to-one relationship. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). @@ -271,7 +271,7 @@ - If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. -- If is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. +- If is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. If the `object` has an and `entitySetName` has a value, then the of the entity key must match the that was found based on the `entitySetName` and entity container name. @@ -329,11 +329,11 @@ method is used to apply changes that were made to objects outside the , such as detached objects that are received by a Web service. The method copies the scalar values from the supplied object into the object in the that has the same key. You can use the of the detached object to retrieve an instance of this object from the data source. For more information, see [How to: Return a Specific Object Using its Key](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896251(v=vs.100)). Any values that differ from the original values of the object are marked as modified. Note, the method does not apply the current values to the related objects of `currentEntity`. + The method is used to apply changes that were made to objects outside the , such as detached objects that are received by a Web service. The method copies the scalar values from the supplied object into the object in the that has the same key. You can use the of the detached object to retrieve an instance of this object from the data source. For more information, see [How to: Return a Specific Object Using its Key](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896251(v=vs.100)). Any values that differ from the original values of the object are marked as modified. Note, the method does not apply the current values to the related objects of `currentEntity`. - If you have a graph with the current values and want to apply the original values, call method. + If you have a graph with the current values and want to apply the original values, call method. - You may also use the of the or method of the . For more information, see [Building N-Tier Applications](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896304(v=vs.100)). + You may also use the of the or method of the . For more information, see [Building N-Tier Applications](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896304(v=vs.100)). ]]> @@ -390,11 +390,11 @@ method is used to apply changes that were made to objects outside the , such as detached objects that are received by a Web service. The method copies the scalar values from the supplied object into the object in the that has the same key. You can use the of the detached object to retrieve an instance of this object from the data source. For more information, see [How to: Return a Specific Object Using its Key](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896251(v=vs.100)). Any values that differ from the current values of the object are marked as modified. Note, the method does not apply the current values to the related objects of `originalEntity`. + The method is used to apply changes that were made to objects outside the , such as detached objects that are received by a Web service. The method copies the scalar values from the supplied object into the object in the that has the same key. You can use the of the detached object to retrieve an instance of this object from the data source. For more information, see [How to: Return a Specific Object Using its Key](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896251(v=vs.100)). Any values that differ from the current values of the object are marked as modified. Note, the method does not apply the current values to the related objects of `originalEntity`. - If you have a graph with the original values and want to apply the current values, call method. + If you have a graph with the original values and want to apply the current values, call method. - You may also use the of the or method of the . For more information, see [Building N-Tier Applications](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896304(v=vs.100)). + You may also use the of the or method of the . For more information, see [Building N-Tier Applications](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896304(v=vs.100)). ]]> @@ -459,17 +459,17 @@ method is used to apply property changes from a modified, detached version of an object to the original version attached to the . This supports scenarios, such as Web services, where an entity object is detached and sent to a remote application where property updates are made. This method enables you to more easily apply these changes back to the original object. + The method is used to apply property changes from a modified, detached version of an object to the original version attached to the . This supports scenarios, such as Web services, where an entity object is detached and sent to a remote application where property updates are made. This method enables you to more easily apply these changes back to the original object. - After , the object is in the state. You must call the method to update the data source. + After , the object is in the state. You must call the method to update the data source. The original object must exist in the and must be in the or state. The original object is only modified if there are modified properties in the `changed` object. The property of the supplied object must be set to a valid . - does not affect navigation properties or related objects. + does not affect navigation properties or related objects. - only sets properties that exist in the entity metadata for the type. For example, properties that are added in a partial class are not included in the operation. + only sets properties that exist in the entity metadata for the type. For example, properties that are added in a partial class are not included in the operation. ]]> @@ -516,15 +516,15 @@ on the to attach the object to the object context. Do this when the object already exists in the data source but is currently not attached to the context. For more information, see [Customizing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738612(v=vs.100)). + Call on the to attach the object to the object context. Do this when the object already exists in the data source but is currently not attached to the context. For more information, see [Customizing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738612(v=vs.100)). - is used to attach an object or the top-level object in an object graph. + is used to attach an object or the top-level object in an object graph. The object being attached must implement to expose an . All generated entity classes implement . - When you attach related objects, you must also call `Attach` on the or the to define the relationship. + When you attach related objects, you must also call `Attach` on the or the to define the relationship. - This method calls the method. + This method calls the method. The following considerations apply when attaching objects: @@ -532,7 +532,7 @@ - Objects are added to the object context in an unchanged state. -- The object that is passed to the method must have a valid value. If the object does not have a valid value, use the method to specify the name of the entity set. +- The object that is passed to the method must have a valid value. If the object does not have a valid value, use the method to specify the name of the entity set. ## Examples In this example, two objects are attached and then the relationship is defined. @@ -574,7 +574,7 @@ on the to attach the object to a specific entity set in the object context or if the object has a `null` (`Nothing` in Visual Basic) value. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + Call on the to attach the object to a specific entity set in the object context or if the object has a `null` (`Nothing` in Visual Basic) value. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). The object being attached can be a single object or be part of the graph. @@ -582,7 +582,7 @@ - If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. -- If the is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. +- If the is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. The object being attached is not required to have an associated with it. If the object does not have an entity key, then `entitySetName` cannot be an empty string. @@ -653,7 +653,7 @@ operation is defined by the underlying connection provider. However, you can override this default timeout value by using the property on . Do this when you have a complex query or when other performance issues cause queries or calls to to time out frequently. + The default timeout for object queries and the operation is defined by the underlying connection provider. However, you can override this default timeout value by using the property on . Do this when you have a complex query or when other performance issues cause queries or calls to to time out frequently. ## Examples [Object queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)) @@ -750,9 +750,9 @@ to view the data definition language (DDL) script. Call to execute the script. + Call to view the data definition language (DDL) script. Call to execute the script. - Most of the work is delegated to the method. + Most of the work is delegated to the method. For more information, see [Working with Data Definition Language](/dotnet/framework/data/adonet/ef/working-with-data-definition-language). @@ -785,9 +785,9 @@ to view the DDL script. Call to execute the script. + Call to view the DDL script. Call to execute the script. - Most of the work is delegated to the method. + Most of the work is delegated to the method. For more information, see [Working with Data Definition Language](/dotnet/framework/data/adonet/ef/working-with-data-definition-language). @@ -826,14 +826,14 @@ does not exist for the `entity`, the method creates a new key for it. + If an does not exist for the `entity`, the method creates a new key for it. - This method is used to determine whether an object that has the same is already attached to the . If an object that has the same is already attached, an exception is raised. Use the method to try to retrieve the of the detached object before calling the method. + This method is used to determine whether an object that has the same is already attached to the . If an object that has the same is already attached, an exception is raised. Use the method to try to retrieve the of the detached object before calling the method. ## Examples - In this example, is used to retrieve the entity key of an existing object. + In this example, is used to retrieve the entity key of an existing object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetapplyitemupdatesgetobject"::: @@ -883,7 +883,7 @@ method is used with POCO custom data classes to make sure that the returned object can be managed correctly by the Entity Framework. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). + The method is used with POCO custom data classes to make sure that the returned object can be managed correctly by the Entity Framework. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). ]]> @@ -1039,7 +1039,7 @@ to create an of the specified type that belongs to the current object context. + Use to create an of the specified type that belongs to the current object context. ## Examples This example creates a simple query and iterates through the collection of results. @@ -1076,7 +1076,7 @@ method. + Most of the work is delegated to the method. For more information, see [Working with Data Definition Language](/dotnet/framework/data/adonet/ef/working-with-data-definition-language). @@ -1109,7 +1109,7 @@ never returns `null`; it either returns the value that was set or an empty string. The user can set this property to `null`, but internally the name will be set to an empty string, so the user never needs to check for both an empty string and `null`. + never returns `null`; it either returns the value that was set or an empty string. The user can set this property to `null`, but internally the name will be set to an empty string, so the user never needs to check for both an empty string and `null`. The default container name is also defined as part of a constructor. If the default container name is set through the protected constructor, the property becomes read-only. @@ -1140,7 +1140,7 @@ method. + Most of the work is delegated to the method. For more information, see [Working with Data Definition Language](/dotnet/framework/data/adonet/ef/working-with-data-definition-language). @@ -1177,11 +1177,11 @@ . The object is deleted in the data source when the method is called. + Marks an object for deletion from the . The object is deleted in the data source when the method is called. Deleting the parent object also deletes all the child objects in the constrained relationship. This result is the same as enabling the `CascadeDelete` property on the association for the relationship. - The method can be called on objects that are already deleted. + The method can be called on objects that are already deleted. ## Examples @@ -1231,14 +1231,14 @@ This example constructs an with a specific ProductI ## Remarks Removes the object from the . This disables change tracking and identity resolution for that object. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). - After the method is called, the system will no longer keep references that point to this object and it can be collected by the garbage collector. + After the method is called, the system will no longer keep references that point to this object and it can be collected by the garbage collector. > [!NOTE] > Garbage collection can only occur if the user code does not have any references to the detached object. The following considerations apply when detaching objects: -- only affects the specific object that is passed to the method. If the object being detached has related objects in the object context, those objects are not detached. +- only affects the specific object that is passed to the method. If the object being detached has related objects in the object context, those objects are not detached. - Detaching objects does not affect data in the data source. @@ -1315,11 +1315,11 @@ This example constructs an with a specific ProductI is called, operations that require an open connection, such as executing a query or calling the method, will cause an exception. Operations that do not require an open connection, such as composing a query or attaching objects, will not cause an exception. The method does not close any explicitly opened connections. + This method closes the connection if it was opened by the Entity Framework. After is called, operations that require an open connection, such as executing a query or calling the method, will cause an exception. Operations that do not require an open connection, such as composing a query or attaching objects, will not cause an exception. The method does not close any explicitly opened connections. Limiting the scope of an within a `using` block (`Using` in Visual Basic) ensures that resources are correctly disposed. For more information, see [Managing Connections and Transactions](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896325(v=vs.100)). - The method calls the `virtual` (`Overridable` in Visual Basic) method. + The method calls the `virtual` (`Overridable` in Visual Basic) method. ]]> @@ -1353,7 +1353,7 @@ This example constructs an with a specific ProductI is called, operations that require an open connection, such as executing a query or calling the method, will cause an exception. Operations that do not require an open connection, such as composing a query or attaching objects, will not cause an exception. + This method closes the connection. After is called, operations that require an open connection, such as executing a query or calling the method, will cause an exception. Operations that do not require an open connection, such as composing a query or attaching objects, will not cause an exception. Limiting the scope of an within a `using` block (`Using` in Visual Basic) ensures that resources are properly disposed. For more information, see [Managing Connections and Transactions](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896325(v=vs.100)). @@ -1462,11 +1462,11 @@ This example constructs an with a specific ProductI method is a helper method that is used to execute stored procedures or functions that are defined in the data source and expressed in the conceptual model. The Entity Data Model tools generate a method for each [FunctionImport Element](/ef/ef6/modeling/designer/advanced/edmx/csdl-spec#functionimport-element-csdl) in the conceptual model. These methods call a strongly-typed `ExecuteFunction` to return a typed . For more information, see [Application Code using Stored Procedures (Entity Framework)](https://learn.microsoft.com/previous-versions/cc716795(v=vs.90)). + The method is a helper method that is used to execute stored procedures or functions that are defined in the data source and expressed in the conceptual model. The Entity Data Model tools generate a method for each [FunctionImport Element](/ef/ef6/modeling/designer/advanced/edmx/csdl-spec#functionimport-element-csdl) in the conceptual model. These methods call a strongly-typed `ExecuteFunction` to return a typed . For more information, see [Application Code using Stored Procedures (Entity Framework)](https://learn.microsoft.com/previous-versions/cc716795(v=vs.90)). All parameters for the function are required in the parameters array and all types are checked against the metadata for the import function, including the type of the function itself. `null` values are permitted for CLR value types. Parameter validation is performed by the provider. - The method uses the value of . Therefore, if an object already exists in the object context, it will not be loaded from the data source. + The method uses the value of . Therefore, if an object already exists in the object context, it will not be loaded from the data source. ]]> @@ -1525,7 +1525,7 @@ This example constructs an with a specific ProductI method is a helper method that is used to execute stored procedures or functions that are defined in the data source and expressed in conceptual model. The Entity Data Model tools generate a method for each [FunctionImport Element](/ef/ef6/modeling/designer/advanced/edmx/csdl-spec#functionimport-element-csdl) in the conceptual model. These methods call a strongly-typed `ExecuteFunction` to return a typed . For more information, see [Application Code using Stored Procedures (Entity Framework)](https://learn.microsoft.com/previous-versions/cc716795(v=vs.90)). + The method is a helper method that is used to execute stored procedures or functions that are defined in the data source and expressed in conceptual model. The Entity Data Model tools generate a method for each [FunctionImport Element](/ef/ef6/modeling/designer/advanced/edmx/csdl-spec#functionimport-element-csdl) in the conceptual model. These methods call a strongly-typed `ExecuteFunction` to return a typed . For more information, see [Application Code using Stored Procedures (Entity Framework)](https://learn.microsoft.com/previous-versions/cc716795(v=vs.90)). All parameters for the function are required in the parameters array and all types are checked against the metadata for the import function, including the type of the function itself. `null` values are permitted for CLR value types. Parameter validation is performed by the provider. @@ -1641,13 +1641,13 @@ This example constructs an with a specific ProductI method uses the existing connection to execute an arbitrary command directly against the data source. The store command is executed in the context of the current transaction, if such a transaction exists. + The method uses the existing connection to execute an arbitrary command directly against the data source. The store command is executed in the context of the current transaction, if such a transaction exists. - Calling the method is equivalent to calling the method of the class, only returns entities and the returns property values in the . + Calling the method is equivalent to calling the method of the class, only returns entities and the returns property values in the . - Call the with the specified entity set name, if you want for the results to be tracked. + Call the with the specified entity set name, if you want for the results to be tracked. - Call the method to translate a into entity objects when the reader contains data rows that map to the specified entity type. + Call the method to translate a into entity objects when the reader contains data rows that map to the specified entity type. Using parameterized commands helps guard against SQL injection attacks, in which an attacker "injects" a command into a SQL statement that compromises security on the server. Parameterized commands guard against a SQL injection attack by guaranteeing that values received from an external source are passed as values only, and not part of the SQL statement. As a result, SQL commands inserted into a value are not executed at the data source. Rather, they are evaluated only as a parameter value. In addition to the security benefits, parameterized commands provide a convenient method for organizing values passed with a SQL statement or to a stored procedure. @@ -1706,13 +1706,13 @@ This example constructs an with a specific ProductI method uses the existing connection to execute an arbitrary command directly against the data source. The store command is executed in the context of the current transaction, if such a transaction exists. + The method uses the existing connection to execute an arbitrary command directly against the data source. The store command is executed in the context of the current transaction, if such a transaction exists. - Calling the method is equivalent to calling the method of the class, only returns entities and the returns property values in the . + Calling the method is equivalent to calling the method of the class, only returns entities and the returns property values in the . Specify the entity set name, if you want for the results to be tracked as entities. - Call method to translate a into entity objects when the reader contains data rows that map to the specified entity type. + Call method to translate a into entity objects when the reader contains data rows that map to the specified entity type. Using parameterized commands helps guard against SQL injection attacks, in which an attacker "injects" a command into a SQL statement that compromises security on the server. Parameterized commands guard against a SQL injection attack by guaranteeing that values received from an external source are passed as values only, and not part of the SQL statement. As a result, SQL commands inserted into a value are not executed at the data source. Rather, they are evaluated only as a parameter value. In addition to the security benefits, parameterized commands provide a convenient method for organizing values passed with a SQL statement or to a stored procedure. @@ -1751,7 +1751,7 @@ This example constructs an with a specific ProductI method is used when proxy object generation is enabled for POCO entities. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). + The method is used when proxy object generation is enabled for POCO entities. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). ]]> @@ -1784,9 +1784,9 @@ This example constructs an with a specific ProductI tries to retrieve an object that has the specified from the . If the object is currently not loaded into the object context, a query is executed in an attempt to return the object from the data source. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + tries to retrieve an object that has the specified from the . If the object is currently not loaded into the object context, a query is executed in an attempt to return the object from the data source. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). - raises an when the object cannot be found. To avoid handling this exception, instead use the method. + raises an when the object cannot be found. To avoid handling this exception, instead use the method. This method will return objects in the state. @@ -1833,7 +1833,7 @@ This example constructs an with a specific ProductI method is used when proxy object generation is enabled for POCO entities. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). + The method is used when proxy object generation is enabled for POCO entities. For more information, see [Requirements for Creating POCO Proxies](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd468057(v=vs.100)) and [Working with POCO Entities](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/dd456853(v=vs.100)). ]]> @@ -1850,7 +1850,7 @@ This example constructs an with a specific ProductI or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1883,13 +1883,13 @@ This example constructs an with a specific ProductI method must be called to achieve explicit loading when you are using POCO custom data classes. + The method must be called to achieve explicit loading when you are using POCO custom data classes. - After calling , the related object can be accessed through the navigation properties of the source entity. + After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . - When the method is called, objects are loaded into the by using the default value of . + When the method is called, objects are loaded into the by using the default value of . ]]> @@ -1929,11 +1929,11 @@ This example constructs an with a specific ProductI method must be called to achieve explicit loading when you are using POCO custom data classes. + The method must be called to achieve explicit loading when you are using POCO custom data classes. - After calling , the related object can be accessed through the navigation properties of the source entity. + After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1975,13 +1975,13 @@ This example constructs an with a specific ProductI method must be called to achieve explicit loading when you are using POCO custom data classes. + The method must be called to achieve explicit loading when you are using POCO custom data classes. - After calling , the related object can be accessed through the navigation properties of the source entity. + After calling , the related object can be accessed through the navigation properties of the source entity. The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName`, where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -2029,13 +2029,13 @@ This example constructs an with a specific ProductI method must be called to achieve explicit loading when you are using POCO custom data classes. + The method must be called to achieve explicit loading when you are using POCO custom data classes. - After calling , the related object can be accessed through the navigation properties of the source entity. + After calling , the related object can be accessed through the navigation properties of the source entity. The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName` where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -2145,7 +2145,7 @@ This example gets the from the method on the returned to get an object based on its entity key. + This example uses the method on the returned to get an object based on its entity key. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetapplyitemupdates"::: @@ -2224,9 +2224,9 @@ This example gets the from the is called, the object's original values will always be updated with the data source value, but the current values might or might not be updated with the data source value. This depends on the value. The mode means that the objects in the collection should be updated to match the data source values. means that only the changes in the object context will be persisted, even if there have been other changes in the data source. + After is called, the object's original values will always be updated with the data source value, but the current values might or might not be updated with the data source value. This depends on the value. The mode means that the objects in the collection should be updated to match the data source values. means that only the changes in the object context will be persisted, even if there have been other changes in the data source. - To ensure that objects have been updated by data source-side logic, you can call with after you call the method. + To ensure that objects have been updated by data source-side logic, you can call with after you call the method. ]]> @@ -2271,13 +2271,13 @@ This example gets the from the has the dual purpose of allowing an object to be refreshed with data from the data source and being the mechanism by which conflicts can be resolved. For more information, see [Saving Changes and Managing Concurrency](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). + has the dual purpose of allowing an object to be refreshed with data from the data source and being the mechanism by which conflicts can be resolved. For more information, see [Saving Changes and Managing Concurrency](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). The order in which objects are refreshed is nondeterministic. - After the method is called, the object's original values will always be updated with the data source value, but the current values might or might not be updated with the data source value. This depends on the . The mode means that the object should be updated to match the data source values. The value means that only the changes in the object context will be persisted, even if there have been other changes in the data source. + After the method is called, the object's original values will always be updated with the data source value, but the current values might or might not be updated with the data source value. This depends on the . The mode means that the object should be updated to match the data source values. The value means that only the changes in the object context will be persisted, even if there have been other changes in the data source. - To ensure that an object has been updated by data source-side logic, you can call the method with the value after you call the method. + To ensure that an object has been updated by data source-side logic, you can call the method with the value after you call the method. @@ -2333,11 +2333,11 @@ This example gets the from the method with the value after you call . For more information, see [Saving Changes and Managing Concurrency](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). + To ensure that objects on the client have been updated by data source-side logic, you can call the method with the value after you call . For more information, see [Saving Changes and Managing Concurrency](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). - operates within a transaction. will roll back that transaction and throw an exception if any of the dirty objects cannot be persisted. + operates within a transaction. will roll back that transaction and throw an exception if any of the dirty objects cannot be persisted. - If an optimistic concurrency violation has occurred, an is thrown. You can resolve an optimistic concurrency violation by catching it, calling the method with the or value, and then calling again. For more information, see [How to: Manage Data Concurrency in the Object Context](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399228(v=vs.100)). + If an optimistic concurrency violation has occurred, an is thrown. You can resolve an optimistic concurrency violation by catching it, calling the method with the or value, and then calling again. For more information, see [How to: Manage Data Concurrency in the Object Context](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399228(v=vs.100)). ## Examples @@ -2392,7 +2392,7 @@ This example tries to save changes, which may cause a concurrency conflict. Then method instead. + Call the method instead. ]]> @@ -2425,13 +2425,13 @@ This example tries to save changes, which may cause a concurrency conflict. Then to either make sure that is called before you save changes to the data source or that is called after you save changes to the data source. + Use this specific overload of to either make sure that is called before you save changes to the data source or that is called after you save changes to the data source. This enumeration has a that allows for a bitwise combination of its member values. - To make sure that objects on the client have been updated by data source-side logic, you can call the method with the value after you call . The method operates in a transaction. will roll back that transaction and throw an exception if any one of the dirty objects cannot be persisted. + To make sure that objects on the client have been updated by data source-side logic, you can call the method with the value after you call . The method operates in a transaction. will roll back that transaction and throw an exception if any one of the dirty objects cannot be persisted. - If an optimistic concurrency violation has occurred, an is thrown. You can resolve an optimistic concurrency violation by catching it, calling the method with the or values, and then calling the method again. For more information, see [How to: Manage Data Concurrency in the Object Context](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399228(v=vs.100)). + If an optimistic concurrency violation has occurred, an is thrown. You can resolve an optimistic concurrency violation by catching it, calling the method with the or values, and then calling the method again. For more information, see [How to: Manage Data Concurrency in the Object Context](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb399228(v=vs.100)). ]]> @@ -2460,7 +2460,7 @@ This example tries to save changes, which may cause a concurrency conflict. Then event is raised at the start of a operation on an . This event is typically used to validate changed objects before new values are written to the database. + The event is raised at the start of a operation on an . This event is typically used to validate changed objects before new values are written to the database. ## Examples This example registers a handler for the event that performs entity state validation. @@ -2502,7 +2502,7 @@ This example tries to save changes, which may cause a concurrency conflict. Then method is used to translate entity data from a into objects of the requested type. This process is performed automatically when an is executed to return entity data. The method enables you to execute a standard ADO.NET query against a data source and translate the returned data rows into entity objects. + The method is used to translate entity data from a into objects of the requested type. This process is performed automatically when an is executed to return entity data. The method enables you to execute a standard ADO.NET query against a data source and translate the returned data rows into entity objects. The supplied must contain data that maps to the requested entity type. @@ -2551,7 +2551,7 @@ This example tries to save changes, which may cause a concurrency conflict. Then method is used to translate entity data from a into objects of the requested type. This process is performed automatically when an is executed to return entity data. The method enables you to execute a standard ADO.NET query against a data source and translate the returned data rows into entity objects. + The method is used to translate entity data from a into objects of the requested type. This process is performed automatically when an is executed to return entity data. The method enables you to execute a standard ADO.NET query against a data source and translate the returned data rows into entity objects. The supplied must contain data that maps to the requested entity type. @@ -2598,15 +2598,15 @@ This example tries to save changes, which may cause a concurrency conflict. Then tries to retrieve an object that has the specified from the . If the object is currently not loaded into the object context, a query is executed in an attempt to return the object from the data source. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + tries to retrieve an object that has the specified from the . If the object is currently not loaded into the object context, a query is executed in an attempt to return the object from the data source. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). - Use the method to avoid handling the raised by when the object cannot be found. + Use the method to avoid handling the raised by when the object cannot be found. This method will return objects in the state. A temporary key cannot be used to return an object from the data source. - The method applies the standard .NET `TryParse` pattern for the method, returning `false` when the is caught. + The method applies the standard .NET `TryParse` pattern for the method, returning `false` when the is caught. diff --git a/xml/System.Data.Objects/ObjectContextOptions.xml b/xml/System.Data.Objects/ObjectContextOptions.xml index 571dd1cec20..779b0a09314 100644 --- a/xml/System.Data.Objects/ObjectContextOptions.xml +++ b/xml/System.Data.Objects/ObjectContextOptions.xml @@ -102,11 +102,11 @@ if the consistent NullReference behavior should be used; otherwise, . - for an FK relationship to null when it is already null will have no effect. When this flag is set to `true`, then setting the value to null will always cause the FK to be nulled and the relationship to be deleted even if the value is currently null. The default value is `false` when using ObjectContext and `true` when using DbContext. - + for an FK relationship to null when it is already null will have no effect. When this flag is set to `true`, then setting the value to null will always cause the FK to be nulled and the relationship to be deleted even if the value is currently null. The default value is `false` when using ObjectContext and `true` when using DbContext. + ]]> diff --git a/xml/System.Data.Objects/ObjectParameter.xml b/xml/System.Data.Objects/ObjectParameter.xml index fd798a12c48..609de34d5e2 100644 --- a/xml/System.Data.Objects/ObjectParameter.xml +++ b/xml/System.Data.Objects/ObjectParameter.xml @@ -20,7 +20,7 @@ or a query builder method. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + Represents a query parameter that is passed to an or a query builder method. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). Object parameters consist of a name, a type, and a value. diff --git a/xml/System.Data.Objects/ObjectParameterCollection.xml b/xml/System.Data.Objects/ObjectParameterCollection.xml index 90482098eee..1b989fcafba 100644 --- a/xml/System.Data.Objects/ObjectParameterCollection.xml +++ b/xml/System.Data.Objects/ObjectParameterCollection.xml @@ -33,15 +33,15 @@ objects defined in an . + Represents the query parameters as objects defined in an . This class cannot be inherited. - The parameters that are passed to query builder methods are aggregated by successive instances of an in the sequence. They can be accessed by using the property, which returns the . After parameters have been added, they can be removed from the collection and the collection can be cleared, as long as the query has not been compiled or executed. Parameter names cannot be changed, but values can be changed at any time. + The parameters that are passed to query builder methods are aggregated by successive instances of an in the sequence. They can be accessed by using the property, which returns the . After parameters have been added, they can be removed from the collection and the collection can be cleared, as long as the query has not been compiled or executed. Parameter names cannot be changed, but values can be changed at any time. Parameters must be unique in the . There cannot be two parameters in the collection with the same name. - When using composition methods, such as , , and , the parameters are merged. An exception is thrown when the sets of parameters are incompatible or incomplete. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + When using composition methods, such as , , and , the parameters are merged. An exception is thrown when the sets of parameters are incompatible or incomplete. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). @@ -207,7 +207,7 @@ method to determine whether the specified parameter is in the collection. + This example uses the method to determine whether the specified parameter is in the collection. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectparametercollection_stringarg"::: @@ -421,7 +421,7 @@ instance. This allows the collection to be iterated through and traversed. + Returns an instance. This allows the collection to be iterated through and traversed. ]]> diff --git a/xml/System.Data.Objects/ObjectQuery.xml b/xml/System.Data.Objects/ObjectQuery.xml index 7c1f0cc55f2..a12657dfa36 100644 --- a/xml/System.Data.Objects/ObjectQuery.xml +++ b/xml/System.Data.Objects/ObjectQuery.xml @@ -34,7 +34,7 @@ is the base class for queries against a conceptual model. is provided to ensure that LINQ to Entities queries have the same functionality as queries executed using . You must use with a specified type to query a conceptual model. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + is the base class for queries against a conceptual model. is provided to ensure that LINQ to Entities queries have the same functionality as queries executed using . You must use with a specified type to query a conceptual model. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). ]]> @@ -93,7 +93,7 @@ ## Examples - This example gets the object associated with this object. + This example gets the object associated with this object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_context"::: @@ -161,7 +161,7 @@ ## Remarks The default merge option for object queries is . For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)). - Call the method on for typed object queries. + Call the method on for typed object queries. ]]> @@ -192,7 +192,7 @@ of type and uses to determine whether the type returned represents a row. + This example creates an of type and uses to determine whether the type returned represents a row. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetgetresulttype"::: @@ -260,7 +260,7 @@ ## Examples - This example adds new parameters to the collection and then gets the parameter collection for this . Then it iterates through the and displays the name, type, and value of each parameter in the collection. + This example adds new parameters to the collection and then gets the parameter collection for this . Then it iterates through the and displays the name, type, and value of each parameter in the collection. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_parameters"::: @@ -302,7 +302,7 @@ executes the query with the merge option that is specified by the property. + Calling executes the query with the merge option that is specified by the property. The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. @@ -339,7 +339,7 @@ instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. This property always returns `false` because the collection returned by the query contains objects and not collections. @@ -380,7 +380,7 @@ instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. This method enables data binding to the result of the query. It is called by the control bound to the collection. For more information, see [Binding Objects to Controls](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738469(v=vs.100)). @@ -414,7 +414,7 @@ instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -454,7 +454,7 @@ ## Remarks For queries built by using LINQ builder patterns, this returns a full LINQ expression tree; otherwise, it returns a constant expression that wraps this query. Note that the default expression is not cached. This allows the framework to differentiate between LINQ and Entity SQL queries. - This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -486,7 +486,7 @@ instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Data.Objects/ObjectQuery`1.xml b/xml/System.Data.Objects/ObjectQuery`1.xml index f07c6eeedef..a420a30acd4 100644 --- a/xml/System.Data.Objects/ObjectQuery`1.xml +++ b/xml/System.Data.Objects/ObjectQuery`1.xml @@ -47,21 +47,21 @@ generic class represents a query that returns a collection of zero or more objects of a specific type. The must be defined before an object query can be executed. This context provides the connection and metadata information that is required to compose and execute the query. An object query is executed in the following scenarios: + The generic class represents a query that returns a collection of zero or more objects of a specific type. The must be defined before an object query can be executed. This context provides the connection and metadata information that is required to compose and execute the query. An object query is executed in the following scenarios: - When it is acted upon, such as during a `foreach` (C#) or `For Each` (Visual Basic) enumeration. -- When it is assigned to fill a collection. +- When it is assigned to fill a collection. -- When the method is explicitly called. +- When the method is explicitly called. - The query itself can be created by using an Entity SQL statement or a LINQ query, or it can be incrementally built by using the query builder methods included in the class. In every case, the result is a new instance that, when explicitly executed or enumerated over, will send the query to the data source for execution and return the results. + The query itself can be created by using an Entity SQL statement or a LINQ query, or it can be incrementally built by using the query builder methods included in the class. In every case, the result is a new instance that, when explicitly executed or enumerated over, will send the query to the data source for execution and return the results. - An is frequently of an entity type, but it can also be of type, for projections to an anonymous type, or of a primitive type, such as an integer or string. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + An is frequently of an entity type, but it can also be of type, for projections to an anonymous type, or of a primitive type, such as an integer or string. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). ## Examples -The following example shows how to construct an instance of the class. +The following example shows how to construct an instance of the class. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery"::: @@ -83,7 +83,7 @@ The following example shows how to construct an instance of the can be initialized in such a way that it represents a single scalar result and not a collection of scalar results. Some extension methods require collection results as input. In this case, an is thrown when one of these methods is called. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + An can be initialized in such a way that it represents a single scalar result and not a collection of scalar results. Some extension methods require collection results as input. In this case, an is thrown when one of these methods is called. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). When your application generates Entity SQL queries at runtime, you should be aware of any command length limitations of the data source. Entity SQL does not enforce limitations on the length of the command text in queries. @@ -122,7 +122,7 @@ The following example shows how to construct an instance of the class. + This example shows how to construct an instance of the class. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery"::: @@ -162,7 +162,7 @@ The following example shows how to construct an instance of the is initialized with the specified query, , and . +In this example, the is initialized with the specified query, , and . :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_select"::: @@ -194,14 +194,14 @@ In this example, the is initialized w instance that is equivalent to the original query with [SELECT DISTINCT](/dotnet/framework/data/adonet/ef/language-reference/select-entity-sql) applied. + This query builder method returns an instance that is equivalent to the original query with [SELECT DISTINCT](/dotnet/framework/data/adonet/ef/language-reference/select-entity-sql) applied. The `DISTINCT` operator cannot be applied to an object that includes a mapping to a non-comparable column in the data source (such as ntext). ## Examples - This example uses method to create a new object. Then it calls on the new object to get the unique results of this query. + This example uses method to create a new object. Then it calls on the new object to get the unique results of this query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_distinct_unionall"::: @@ -237,16 +237,16 @@ In this example, the is initialized w . + The supplied `query` that defines results to exclude must be of the same type or of a type that is compatible with the . - Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - The resulting query inherits the connection from the instance on which was called. + The resulting query inherits the connection from the instance on which was called. ## Examples - This example uses method to create a new object and then iterates through the result of the new query. + This example uses method to create a new object and then iterates through the result of the new query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_except"::: @@ -288,7 +288,7 @@ In this example, the is initialized w ## Examples - This example returns an from method. Then it gets an enumerator and iterates through the query results. At the end it releases the enumerator and the object. + This example returns an from method. Then it gets an enumerator and iterates through the query results. At the end it releases the enumerator and the object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetqueryresult"::: @@ -335,11 +335,11 @@ In this example, the is initialized w applies the projection specified by the `projection` parameter. This means that the returned by the method is always of type . For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + applies the projection specified by the `projection` parameter. This means that the returned by the method is always of type . For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). ## Examples -This example creates a new object that contains the results of the existing query grouped by product name. +This example creates a new object that contains the results of the existing query grouped by product name. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_groupby"::: @@ -388,9 +388,9 @@ This example creates a new object tha Paths are all-inclusive. For example, if an include call indicates `Include("Orders.OrderLines")`, not only will `OrderLines` be included, but also `Orders`. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). - When you call the method, the query path is only valid on the returned instance of the . Other instances of and the object context itself are not affected. + When you call the method, the query path is only valid on the returned instance of the . Other instances of and the object context itself are not affected. - Because the method returns the query object, you can call this method multiple times on an to specify multiple paths for the query, as in the following example: + Because the method returns the query object, you can call this method multiple times on an to specify multiple paths for the query, as in the following example: :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetspanonlywithmultiplepaths"::: @@ -435,15 +435,15 @@ This example creates a new object tha . + The supplied `query` that defines results to include must be of the same type or of a type that is compatible with the . - Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - The resulting query inherits the connection from the instance on which the method was called. + The resulting query inherits the connection from the instance on which the method was called. ## Examples -This example creates a new object that contains the results of two other queries. +This example creates a new object that contains the results of two other queries. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_intersect"::: @@ -484,13 +484,13 @@ This example creates a new object tha ## Remarks The name of the object query identifies the current object query in the sequence by name when constructing query builder methods. By default, the query name is `it`. This can be useful when referring to the current sequence in joins inside the method or in the method. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - When you set the property of an , that value becomes the alias in successive methods. + When you set the property of an , that value becomes the alias in successive methods. - The value of the property must start with a letter and can contain letters, digits, and underscores. + The value of the property must start with a letter and can contain letters, digits, and underscores. ## Examples -This example sets the name of the first to "product" and then uses this alias in the successive method. +This example sets the name of the first to "product" and then uses this alias in the successive method. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetquerywithaliasnamed"::: @@ -530,7 +530,7 @@ This example sets the name of the first is used to filter query results by a specific entity or complex type. This supports a conceptual model with object inheritance. For more information, see [Entity Data Model: Inheritance](/dotnet/framework/data/adonet/entity-data-model-inheritance). -The method can only be applied to an of an entity type or complex type that is defined in the EDM. +The method can only be applied to an of an entity type or complex type that is defined in the EDM. ]]> @@ -576,12 +576,12 @@ The method can only be applied ## Remarks The ordering of results in a nested query cannot be guaranteed. - should always be the final query builder method in the sequence. + should always be the final query builder method in the sequence. ## Examples - This example creates a new object that contains the results of the existing query order by `ProductID`. + This example creates a new object that contains the results of the existing query order by `ProductID`. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_orderby"::: @@ -629,12 +629,12 @@ The method can only be applied applies the projection specified by the `projection` parameter. The returned by the method is always a row type of . Use the method to return values that are simple types, entity types, or complex types. For more information, see [LINQ to Entities](/dotnet/framework/data/adonet/ef/language-reference/linq-to-entities). + applies the projection specified by the `projection` parameter. The returned by the method is always a row type of . Use the method to return values that are simple types, entity types, or complex types. For more information, see [LINQ to Entities](/dotnet/framework/data/adonet/ef/language-reference/linq-to-entities). When a navigation property is included in the projection, the query results include a collection of nested objects. ## Examples - This example creates a new whose results are data records that contain the `ProductID` fields of the results of this query. + This example creates a new whose results are data records that contain the `ProductID` fields of the results of this query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_select"::: @@ -690,14 +690,14 @@ The method can only be applied is used to return values that are simple types, entity types, or complex types. Use the method for projections that require a row type instead of a value type. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). + is used to return values that are simple types, entity types, or complex types. Use the method for projections that require a row type instead of a value type. For more information, see [Object Queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)). - The method applies the projection specified by the `projection` parameter. The returned by the method must be of a value type that is compatible with the projection and must be the same type as the type of . + The method applies the projection specified by the `projection` parameter. The returned by the method must be of a value type that is compatible with the projection and must be the same type as the type of . ## Examples - This example creates a new that contains results that are a sequence of `ProductID` values projected from the results of the existing query. + This example creates a new that contains results that are a sequence of `ProductID` values projected from the results of the existing query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_selectvalue"::: @@ -751,7 +751,7 @@ The method can only be applied method cannot be used after the method. When you use after , it functions like the [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) statement of an `ORDER BY` clause. + The method cannot be used after the method. When you use after , it functions like the [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) statement of an `ORDER BY` clause. @@ -799,7 +799,7 @@ The method can only be applied executes the query. + Calling executes the query. ]]> @@ -842,17 +842,17 @@ The method can only be applied is nondeterministic unless the query is sorted. + is nondeterministic unless the query is sorted. - When you use the method after the method, it functions like the [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) statement of an [ORDER BY](/dotnet/framework/data/adonet/ef/language-reference/order-by-entity-sql) clause. + When you use the method after the method, it functions like the [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) statement of an [ORDER BY](/dotnet/framework/data/adonet/ef/language-reference/order-by-entity-sql) clause. ## Examples -This example creates a new that contains the first two results of the existing query. +This example creates a new that contains the first two results of the existing query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_top"::: - This example gets five `Product` objects after skipping the first three in the query result, sorted by `Product.ListPrice`. is used instead of [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) for paging. + This example gets five `Product` objects after skipping the first three in the query result, sorted by `Product.ListPrice`. is used instead of [LIMIT](/dotnet/framework/data/adonet/ef/language-reference/limit-entity-sql) for paging. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetprojection_skiplimit"::: @@ -892,9 +892,9 @@ This example creates a new that conta adds the results of the supplied `query` without any duplicates. + adds the results of the supplied `query` without any duplicates. - The supplied `query` that defines the results to add must be of the same type or of a type that can be promoted to the type of this . For example, the following is valid because `DiscontinuedProducts` can be promoted to `Products`: + The supplied `query` that defines the results to add must be of the same type or of a type that can be promoted to the type of this . For example, the following is valid because `DiscontinuedProducts` can be promoted to `Products`: ```csharp ObjectQuery.Union(ObjectQuery) @@ -906,16 +906,16 @@ ObjectQuery.Union(ObjectQuery) ObjectQuery .Union(ObjectQuery) ``` - For an of type , the records in both queries must have the same number of columns, and the types in the columns of the of the passed `query` must be promotable to the types of the columns in the of the . + For an of type , the records in both queries must have the same number of columns, and the types in the columns of the of the passed `query` must be promotable to the types of the columns in the of the . - Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - The resulting query inherits the connection from the instance on which was called. + The resulting query inherits the connection from the instance on which was called. ## Examples - This example uses method to creates a new object. + This example uses method to creates a new object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_distinct_union"::: @@ -952,9 +952,9 @@ ObjectQuery .Union(ObjectQuery) adds the results of the supplied `query` including all duplicates. + adds the results of the supplied `query` including all duplicates. - The supplied `query` that defines results to add must be of the same type or of a type that can be promoted to the type of this . For example, the following is valid because `DiscontinuedProducts` can be promoted to `Products`: + The supplied `query` that defines results to add must be of the same type or of a type that can be promoted to the type of this . For example, the following is valid because `DiscontinuedProducts` can be promoted to `Products`: ```csharp ObjectQuery.Union(ObjectQuery) @@ -966,16 +966,16 @@ ObjectQuery.Union(ObjectQuery) ObjectQuery .Union(ObjectQuery) ``` - For an of type , the records in both queries must have the same number of columns, and the types in the columns of the of the passed `query` must be promotable to the types of the columns in the of the . + For an of type , the records in both queries must have the same number of columns, and the types in the columns of the of the passed `query` must be promotable to the types of the columns in the of the . - Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + Parameters that are defined in the supplied `query` are merged with parameters that are defined in the instance. Parameters must be unique in the combined . There cannot be two parameters in the combined collection with the same name. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - The resulting query inherits the connection from the instance on which was called. + The resulting query inherits the connection from the instance on which was called. ## Examples - This example uses the method to create a new object. Then it calls the method on the new object to get the unique results of this query. + This example uses the method to create a new object. Then it calls the method on the new object to get the unique results of this query. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_distinct_unionall"::: @@ -1021,7 +1021,7 @@ ObjectQuery .Union(ObjectQuery) that contains results of the existing query filtered by the following criteria: `"it.ProductID = 900"`. + This example creates a new that contains results of the existing query filtered by the following criteria: `"it.ProductID = 900"`. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_where"::: diff --git a/xml/System.Data.Objects/ObjectResult`1.xml b/xml/System.Data.Objects/ObjectResult`1.xml index bccb83d07ec..324a49dc47c 100644 --- a/xml/System.Data.Objects/ObjectResult`1.xml +++ b/xml/System.Data.Objects/ObjectResult`1.xml @@ -31,11 +31,11 @@ and . Instances of this class are returned from the method and from the method. + This class implements and . Instances of this class are returned from the method and from the method. ## Examples -The following example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. +The following example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectquery_execute"::: @@ -72,7 +72,7 @@ The following example returns an fro ## Examples - This example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. + This example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetqueryresult"::: @@ -135,7 +135,7 @@ The following example returns an fro ## Examples - This example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. + This example returns an from the method. Then it gets an enumerator and iterates through the query results. At the end, it releases the enumerator and the object. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetqueryresult"::: diff --git a/xml/System.Data.Objects/ObjectSet`1.xml b/xml/System.Data.Objects/ObjectSet`1.xml index eb81a11ddcc..1d072009f9d 100644 --- a/xml/System.Data.Objects/ObjectSet`1.xml +++ b/xml/System.Data.Objects/ObjectSet`1.xml @@ -47,11 +47,11 @@ The entity type. Represents a typed entity set that is used to perform create, read, update, and delete operations. - class allows you to operate on a typed entity set without having to specify the entity set name as an argument to each method call. The class extends the functionality of the class to provide object context functionality, such as adding and deleting objects, in the context of a typed entity set that is accessed from the . - + class allows you to operate on a typed entity set without having to specify the entity set name as an argument to each method call. The class extends the functionality of the class to provide object context functionality, such as adding and deleting objects, in the context of a typed entity set that is accessed from the . + ]]> @@ -81,11 +81,11 @@ The object to add. Adds an object to the object context in the current entity set. - method. - + method. + ]]> @@ -114,11 +114,11 @@ Copies the scalar values from the supplied object into the object in the that has the same key. The updated object. - method. - + method. + ]]> @@ -148,11 +148,11 @@ Sets the property of an to match the property values of a supplied object. The updated object. - method. - + method. + ]]> @@ -184,11 +184,11 @@ The object to attach. Attaches an object or object graph to the object context in the current entity set. - method. - + method. + ]]> @@ -272,11 +272,11 @@ An object that represents the entity to delete. The object can be in any state except . Marks an object for deletion. - method. - + method. + ]]> @@ -307,11 +307,11 @@ Object to be detached. Only the is removed; if there are any related objects that are being tracked by the same , those will not be detached automatically. Removes the object from the object context. - method. - + method. + ]]> diff --git a/xml/System.Data.Objects/ObjectStateManager.xml b/xml/System.Data.Objects/ObjectStateManager.xml index 5ed8d057aa7..504af55abea 100644 --- a/xml/System.Data.Objects/ObjectStateManager.xml +++ b/xml/System.Data.Objects/ObjectStateManager.xml @@ -30,7 +30,7 @@ The following example gets the fro :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetobjectstatemanager"::: - The following example uses the method on the returned to get an object based on its entity key. + The following example uses the method on the returned to get an object based on its entity key. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetapplyitemupdates"::: @@ -94,7 +94,7 @@ The following example gets the fro method to change the state of an object to does not cause related objects in a constrained relationship to be deleted. + Calling the method to change the state of an object to does not cause related objects in a constrained relationship to be deleted. Changing the state of an object does not affect related objects in the object graph. @@ -368,7 +368,7 @@ The following example gets the fro method to return an object without having to handle the raised by the method. + Use the method to return an object without having to handle the raised by the method. @@ -411,7 +411,7 @@ The following example gets the fro method to return an object without having to handle the raised by the method. + Use the method to return an object without having to handle the raised by the method. ]]> @@ -444,9 +444,9 @@ The following example gets the fro method is the same as calling the method, except that this method raises an exception instead of returning `false`. + Calling the method is the same as calling the method, except that this method raises an exception instead of returning `false`. - Call the method to avoid handling the that occurs when a cannot be returned for the supplied entity. + Call the method to avoid handling the that occurs when a cannot be returned for the supplied entity. ]]> @@ -551,7 +551,7 @@ The following example gets the fro to return an without having to handle the raised by the method. + Use to return an without having to handle the raised by the method. ## Examples @@ -559,7 +559,7 @@ The following example attempts to retrieve the corresponding method on the returned to get an object based on its entity key. + The following example uses the method on the returned to get an object based on its entity key. :::code language="csharp" source="~/snippets/csharp/System.Data/EntityKey/Overview/Source.cs" id="Snippetapplyitemupdates"::: @@ -597,7 +597,7 @@ The following example attempts to retrieve the corresponding method to return an without having to handle the raised by the method. + Use the method to return an without having to handle the raised by the method. ]]> @@ -632,11 +632,11 @@ The following example attempts to retrieve the corresponding method is used to obtain the for objects that are persistence ignorant. When objects implement or inherit from , the is accessed from the property. + The method is used to obtain the for objects that are persistence ignorant. When objects implement or inherit from , the is accessed from the property. The cannot be returned when the object is in a state. - Calling the method is the same as calling the method, except that this method returns `false` instead of raising an exception. + Calling the method is the same as calling the method, except that this method returns `false` instead of raising an exception. ]]> diff --git a/xml/System.Data.Odbc/OdbcCommand.xml b/xml/System.Data.Odbc/OdbcCommand.xml index 4a34a6f34ab..0e5b01afad9 100644 --- a/xml/System.Data.Odbc/OdbcCommand.xml +++ b/xml/System.Data.Odbc/OdbcCommand.xml @@ -85,9 +85,9 @@ |Item|Description| |----------|-----------------| -||Executes commands that return rows.| -||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| -||Retrieves a single value, for example, an aggregate value, from a database.| +||Executes commands that return rows.| +||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| +||Retrieves a single value, for example, an aggregate value, from a database.| You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. @@ -96,7 +96,7 @@ ## Examples - The following example uses . + The following example uses . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcCommand/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcCommand/Overview/source.vb" id="Snippet1"::: @@ -146,10 +146,10 @@ |Properties|Initial Value| |----------------|-------------------| -||empty string ("")| -||30| -||`Text`| -||null| +||empty string ("")| +||30| +||`Text`| +||null| ]]> @@ -255,10 +255,10 @@ |Properties|Initial Value| |----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||A new that is the value for the `connection` parameter.| +||`cmdText`| +||30| +||`Text`| +||A new that is the value for the `connection` parameter.| You can change the value for any one of these parameters by setting the related property. @@ -305,7 +305,7 @@ ## Remarks If there is nothing to cancel, nothing occurs. However, if there is a command in process, and the cancellation try fails, no exception is generated. - To cancel a query on one thread, must be called from another thread. Because you cannot execute commands asynchronously with , to cancel a command from another thread, one thread must be running synchronously. This means that the object must be accessible from both threads. + To cancel a query on one thread, must be called from another thread. Because you cannot execute commands asynchronously with , to cancel a command from another thread, one thread must be running synchronously. This means that the object must be accessible from both threads. ]]> @@ -372,7 +372,7 @@ property is set to `StoredProcedure`, the property should be set using standard ODBC stored procedure escape sequences. Setting the to the name of the stored procedure does not function as it does for other .NET Framework data providers. + When the property is set to `StoredProcedure`, the property should be set using standard ODBC stored procedure escape sequences. Setting the to the name of the stored procedure does not function as it does for other .NET Framework data providers. Many language features, such as outer joins and scalar function calls, are generally implemented by data sources. Even the syntax for these features is generally data source-specific. Therefore, ODBC defines escape sequences that contain standard syntax for the following language features: @@ -402,11 +402,11 @@ where `procedure-name` specifies the name of a procedure and `parameter` specifies a procedure parameter. - The command executes this stored procedure when you call one of the Execute methods (for example, or ). + The command executes this stored procedure when you call one of the Execute methods (for example, or ). - You cannot set the , and properties if the current connection is performing an execute or fetch operation. + You cannot set the , and properties if the current connection is performing an execute or fetch operation. - The ODBC.NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: + The ODBC.NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: ``` SELECT * FROM Customers WHERE CustomerID = ? @@ -540,9 +540,9 @@ SELECT * FROM Customers WHERE CustomerID = ? property is set to `StoredProcedure`, you should set the property to the full ODBC call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). + When the property is set to `StoredProcedure`, you should set the property to the full ODBC call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). - The , and properties cannot be set if the current connection is performing an execute or fetch operation. + The , and properties cannot be set if the current connection is performing an execute or fetch operation. The .NET Framework Data Provider for ODBC does not support passing named parameters to an SQL statement or to a stored procedure called by an . In either of these cases, use the question mark (?) placeholder. For example: @@ -610,9 +610,9 @@ SELECT * FROM Customers WHERE CustomerID = ? , , and properties if the current connection is performing an execute or fetch operation. + You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. + If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. ]]> @@ -680,7 +680,7 @@ SELECT * FROM Customers WHERE CustomerID = ? method is a strongly-typed version of . + The method is a strongly-typed version of . ]]> @@ -920,11 +920,11 @@ SELECT * FROM Customers WHERE CustomerID = ? to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. + You can use to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. - You can also use to execute multiple SQL statements if the underlying ODBC driver supports this functionality. In this case, the return value is the number of rows affected by all statements in the command. + You can also use to execute multiple SQL statements if the underlying ODBC driver supports this functionality. In this case, the return value is the number of rows affected by all statements in the command. - Although returns no rows, any output parameters or return values mapped to parameters are populated with data. + Although returns no rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. If a rollback occurs, the return value is also -1. @@ -980,9 +980,9 @@ SELECT * FROM Customers WHERE CustomerID = ? property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . + You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . - While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the is called. + While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the is called. ]]> @@ -1024,14 +1024,14 @@ SELECT * FROM Customers WHERE CustomerID = ? ## Remarks If you expect your SQL statement to return only a single row, specifying `SingleRow` as the value may improve application performance. - You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . + You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . > [!NOTE] > The `SequentialAccess` value of is not a limiting setting; it just means that you will have at least sequential access to the . For example, when you use the SQL Server ODBC Driver in `SequentialAccess` mode, you can still move to the first column of an row after having read through all the other columns sequentially. - While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until you call the method. If the is created with set to `CloseConnection`, closing the closes the connection automatically. + While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until you call the method. If the is created with set to `CloseConnection`, closing the closes the connection automatically. ]]> @@ -1076,7 +1076,7 @@ SELECT * FROM Customers WHERE CustomerID = ? method to retrieve a single value (for example, an aggregate value) from a data source. This requires less code than using the method, and then performing the operations required to generate the single value from the data returned by an . + Use the method to retrieve a single value (for example, an aggregate value) from a data source. This requires less code than using the method, and then performing the operations required to generate the single value from the data returned by an . ]]> @@ -1121,7 +1121,7 @@ SELECT * FROM Customers WHERE CustomerID = ? is set to `Text`, the .NET Framework Data Provider for ODBC does not support passing named parameters to an SQL statement or to a stored procedure called by an . In either of these cases, use the question mark (?) placeholder. For example: + When is set to `Text`, the .NET Framework Data Provider for ODBC does not support passing named parameters to an SQL statement or to a stored procedure called by an . In either of these cases, use the question mark (?) placeholder. For example: ``` SELECT * FROM Customers WHERE CustomerID = ? @@ -1174,11 +1174,11 @@ SELECT * FROM Customers WHERE CustomerID = ? method calls the ODBC `SQLPrepare` function. Depending on the capabilities of the underlying ODBC driver and data source, parameter information such as data types may be checked when the statement is prepared, if all parameters have been bound, or when it is executed if not all parameters have been bound. For maximum interoperability, an application should unbind all parameters that applied to a previous SQL statement before preparing a new SQL statement on the same . This prevents errors that are caused by previous parameter information being applied to the new SQL statement. + The method calls the ODBC `SQLPrepare` function. Depending on the capabilities of the underlying ODBC driver and data source, parameter information such as data types may be checked when the statement is prepared, if all parameters have been bound, or when it is executed if not all parameters have been bound. For maximum interoperability, an application should unbind all parameters that applied to a previous SQL statement before preparing a new SQL statement on the same . This prevents errors that are caused by previous parameter information being applied to the new SQL statement. - If you call an Execute method after you call , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + If you call an Execute method after you call , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. - Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . + Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . ]]> @@ -1218,7 +1218,7 @@ SELECT * FROM Customers WHERE CustomerID = ? is 30 seconds. + The default value of the is 30 seconds. ]]> diff --git a/xml/System.Data.Odbc/OdbcCommandBuilder.xml b/xml/System.Data.Odbc/OdbcCommandBuilder.xml index 6e5d4619494..3783e5bbc90 100644 --- a/xml/System.Data.Odbc/OdbcCommandBuilder.xml +++ b/xml/System.Data.Odbc/OdbcCommandBuilder.xml @@ -49,14 +49,14 @@ The relationship between an and its corresponding is always one-to-one. To create this correspondence, you set the property of the object. This causes the to register itself as a listener, which produces the output of events that affect the . - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. If you change the value of after the metadata has been retrieved, such as after the first update, you should then call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. If you change the value of after the metadata has been retrieved, such as after the first update, you should then call the method to update the metadata. > [!NOTE] > If the SELECT statement assigned to the property uses aliased column names, the resulting INSERT, UPDATE, and DELETE statements may be inaccurate or fail. If the underlying ODBC driver cannot provide the appropriate base column name for the alias column name (using the SQL_DESC_BASE_COLUMN_NAME value of `SQLColAttribute`), the alias name could be used in the generated INSERT, UPDATE, and DELETE statements. For example, the Microsoft ODBC Driver for Oracle returns the alias name as the base column name. Therefore, the generated INSERT, UPDATE, and DELETE statements would cause errors. - The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the value of the property itself is changed. Otherwise the , , and properties retain their previous values. + The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the value of the property itself is changed. Otherwise the , , and properties retain their previous values. - If you call , the is disassociated from the , and the generated commands are no longer used. + If you call , the is disassociated from the , and the generated commands are no longer used. @@ -264,11 +264,11 @@ overwrites any existing parameter information for the . + overwrites any existing parameter information for the . - requires an additional call to the data source to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. + requires an additional call to the data source to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. - You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. + You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. ]]> @@ -314,11 +314,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -355,11 +355,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -397,11 +397,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -427,11 +427,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -468,11 +468,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -510,11 +510,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -630,11 +630,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -671,11 +671,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -713,11 +713,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, you must explicitly call if it changes the statement in any way. Otherwise, the still will be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: diff --git a/xml/System.Data.Odbc/OdbcConnection.xml b/xml/System.Data.Odbc/OdbcConnection.xml index 0bdfd7dd1dc..852116c237b 100644 --- a/xml/System.Data.Odbc/OdbcConnection.xml +++ b/xml/System.Data.Odbc/OdbcConnection.xml @@ -63,7 +63,7 @@ ## Remarks An object represents a unique connection to a data source created by using a connection string or ODBC data source name (DSN). With a client/server database system, it is equivalent to a network connection to the server. Depending on the functionality supported by the native ODBC driver, some methods or properties of an object may not be available. - The object uses native resources such as ODBC environment and connection handles. You should always explicitly close any open objects by calling or **Dispose** before the object goes out of scope, or by placing the connection within a `Using` statement. Not doing this leaves the freeing of these native resources to garbage collection. It might not free them immediately. This, in turn, can eventually cause the underlying driver to run out of resources or reach a maximum limit. This has resulted in intermittent failures. For example, you might experience `Maximum Connections` -related errors while many connections are waiting to be deleted by the garbage collector. Explicitly closing the connections allows for a more efficient use of native resources, enhancing scalability and improving overall application performance. + The object uses native resources such as ODBC environment and connection handles. You should always explicitly close any open objects by calling or **Dispose** before the object goes out of scope, or by placing the connection within a `Using` statement. Not doing this leaves the freeing of these native resources to garbage collection. It might not free them immediately. This, in turn, can eventually cause the underlying driver to run out of resources or reach a maximum limit. This has resulted in intermittent failures. For example, you might experience `Maximum Connections` -related errors while many connections are waiting to be deleted by the garbage collector. Explicitly closing the connections allows for a more efficient use of native resources, enhancing scalability and improving overall application performance. > [!NOTE] > To deploy high-performance applications, you frequently must use connection pooling. However, when you use the .NET Framework Data Provider for ODBC, you do not have to enable connection pooling because the provider manages this automatically. @@ -77,7 +77,7 @@ ## Examples - The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. + The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/Overview/source.vb" id="Snippet1"::: @@ -125,9 +125,9 @@ |Properties|Initial value| |----------------|-------------------| -||empty string ("")| -||15| -||empty string ("")| +||empty string ("")| +||15| +||empty string ("")| You can change the value for these properties only by using the property. @@ -177,9 +177,9 @@ |Properties|Initial value| |----------------|-------------------| -||`connectionString`| -||15| -||empty string ("")| +||`connectionString`| +||15| +||empty string ("")| You can change the value for these properties only by using the property. @@ -266,17 +266,17 @@ or methods. + To commit or roll back the transaction, you must explicitly use the or methods. To make sure that the .NET Framework Data Provider for ODBC transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. > [!NOTE] -> If you do not specify an isolation level, the isolation level will be determined by the driver being used. To specify an isolation level with the method, use the overload that takes the `isolevel` parameter. +> If you do not specify an isolation level, the isolation level will be determined by the driver being used. To specify an isolation level with the method, use the overload that takes the `isolevel` parameter. ## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. + The following example creates an and an . It also demonstrates how to use the , , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: @@ -320,14 +320,14 @@ or methods. + To commit or roll back the transaction, you must explicitly use the or methods. To make sure that the .NET Framework Data Provider for ODBC transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. ## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. + The following example creates an and an . It also demonstrates how to use the , , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: @@ -431,15 +431,15 @@ method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. If is called while handling a event, no additional events are fired. + The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. If is called while handling a event, no additional events are fired. - An application can call more than one time without generating an exception. + An application can call more than one time without generating an exception. > [!NOTE] > When you use the .NET Framework Data Provider for ODBC, you do not have to enable connection pooling because the ODBC Driver Manager manages this automatically. For more information about how to enable and disabling connection pooling, see the Microsoft Open Database Connectivity (ODBC) documentation. > [!CAUTION] -> Do not call or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). +> Do not call or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). @@ -518,7 +518,7 @@ property is designed to match ODBC connection string format as closely as possible. The can be set only when the connection is closed, and as soon as it is set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the must exactly match what the Driver Manager and underlying driver support. + The property is designed to match ODBC connection string format as closely as possible. The can be set only when the connection is closed, and as soon as it is set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the must exactly match what the Driver Manager and underlying driver support. You can use the property to connect to a variety of data sources. This includes an ODBC data source name (DSN). The following example illustrates several possible connection strings. @@ -537,11 +537,11 @@ ``` > [!NOTE] -> The .NET Framework Data Provider for ODBC does not support the `Persist Security Info` keyword that is supported by other .NET Framework data providers. However, the property behaves as if `Persist Security Info` were set to `false`. This means that you cannot retrieve the password from the property if the connection has been opened. When the property is read from an object that has been opened, the connection string is returned minus the password. You cannot change this behavior; therefore, if the application requires the password, store it separately before calling . +> The .NET Framework Data Provider for ODBC does not support the `Persist Security Info` keyword that is supported by other .NET Framework data providers. However, the property behaves as if `Persist Security Info` were set to `false`. This means that you cannot retrieve the password from the property if the connection has been opened. When the property is read from an object that has been opened, the connection string is returned minus the password. You cannot change this behavior; therefore, if the application requires the password, store it separately before calling . - Many of the settings specified in the string have corresponding read-only properties (for example, `Server=(local)`, which corresponds to the property). These properties are updated after the connection is opened, except when an error is detected. In this case, none of the properties are updated. properties (such as ) return only default settings or those settings specified in the . + Many of the settings specified in the string have corresponding read-only properties (for example, `Server=(local)`, which corresponds to the property). These properties are updated after the connection is opened, except when an error is detected. In this case, none of the properties are updated. properties (such as ) return only default settings or those settings specified in the . -Some basic validation of the connection string occurs as soon as you set the property. At that time, the data provider verifies that the connection string meets the "keyword=value;..." format, but it does not verify whether keywords or values are valid. The remaining verification is performed by the underlying ODBC driver when the application calls the method. +Some basic validation of the connection string occurs as soon as you set the property. At that time, the data provider verifies that the connection string meets the "keyword=value;..." format, but it does not verify whether keywords or values are valid. The remaining verification is performed by the underlying ODBC driver when the application calls the method. An ODBC connection string has the following syntax: @@ -613,7 +613,7 @@ driver-defined-attribute-keyword ::= identifier property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. + Unlike the .NET Framework data providers for SQL Server and OLE DB, the .NET Framework Data Provider for ODBC does not support setting this property as a connection string value, because it is not a valid ODBC connection keyword. To specify a connection time-out, set the property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. ]]> @@ -718,7 +718,7 @@ driver-defined-attribute-keyword ::= identifier property is set in the connection string. The property can be updated by using the method. If you change the current database using an SQL statement or the method, an informational message is sent and then the property is updated. + At first, the property is set in the connection string. The property can be updated by using the method. If you change the current database using an SQL statement or the method, an informational message is sent and then the property is updated. Retrieving the property is equivalent to calling the ODBC function `SQLGetInfo` with the `Attribute` parameter set to SQL_ATTR_CURRENT_CATALOG. @@ -896,11 +896,11 @@ driver-defined-attribute-keyword ::= identifier method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). You can continue to enlist in an existing distributed transaction using the method if auto-enlistment is disabled. Enlisting in an existing distributed transaction makes sure that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). - returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . + returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . ]]> @@ -935,7 +935,7 @@ driver-defined-attribute-keyword ::= identifier method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). ]]> @@ -1155,7 +1155,7 @@ driver-defined-attribute-keyword ::= identifier The draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to the data source. > [!NOTE] -> If the goes out of scope, the connection it represents does not close automatically. Therefore, you must explicitly close the connection by calling , **Dispose**, or by placing the connection within a `Using` statement. +> If the goes out of scope, the connection it represents does not close automatically. Therefore, you must explicitly close the connection by calling , **Dispose**, or by placing the connection within a `Using` statement. ]]> @@ -1195,15 +1195,15 @@ driver-defined-attribute-keyword ::= identifier The following must occur before the environment is finally disposed: -1. Call to release the object from the environment. +1. Call to release the object from the environment. 2. Allow each connection object to time out. -3. Call . +3. Call . 4. Invoke garbage collection. - Conversely, if you call on all active connections, and invoke garbage collection, but do not call , the resources reserved for the environment remain available. + Conversely, if you call on all active connections, and invoke garbage collection, but do not call , the resources reserved for the environment remain available. After an environment handle is released, a request for a new creates a new environment. @@ -1253,7 +1253,7 @@ driver-defined-attribute-keyword ::= identifier is not supported by the underlying ODBC driver, an empty string ("") is returned. + If is not supported by the underlying ODBC driver, an empty string ("") is returned. The property takes the form '*##.##.####*,' where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The driver must render the product version in this form but can also append the product-specific version as a string (for example, "04.01.0000 Rdb 4.1"). This string takes the form '*major.minor.build*' where *major* and *minor* are exactly two digits and *build* is exactly four digits. @@ -1309,9 +1309,9 @@ driver-defined-attribute-keyword ::= identifier ## Remarks The following are allowed state changes: -- From `Closed` to `Open`, using the method. +- From `Closed` to `Open`, using the method. -- From `Open` to `Closed`, using either the or **Dispose** method. +- From `Open` to `Closed`, using either the or **Dispose** method. > [!NOTE] > Calling the property on an open connection increases application overhead because each such call causes a SQL_ATTR_CONNECTION_DEAD call to the underlying ODBC driver to determine whether the connection is still valid. diff --git a/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml b/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml index 7167c36dead..7577577980f 100644 --- a/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml +++ b/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml @@ -55,10 +55,10 @@ |Key|Property|Comment|Default value| |---------|--------------|-------------|-------------------| -|Driver||Developers should not include the braces surrounding the driver name when they set the property. The instance adds braces as needed.|Empty string| -|DSN|||Empty string| +|Driver||Developers should not include the braces surrounding the driver name when they set the property. The instance adds braces as needed.|Empty string| +|DSN|||Empty string| - If any value (other than the value) within the connection string contains a semicolon (;), the surrounds the value with quotation marks in the connection string. In order to avoid this issue with the value that frequently contains a semicolon, the class always surrounds this value with braces. The ODBC specification indicates that driver values that contain semicolons must be surrounded with braces, and this class handles this for you. + If any value (other than the value) within the connection string contains a semicolon (;), the surrounds the value with quotation marks in the connection string. In order to avoid this issue with the value that frequently contains a semicolon, the class always surrounds this value with braces. The ODBC specification indicates that driver values that contain semicolons must be surrounded with braces, and this class handles this for you. The property handles attempts to insert malicious code. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair. @@ -196,7 +196,7 @@ You can pass a connection string in the constructor, or you can set the method removes all key/value pairs from the and resets the and properties to their default values. The method also sets the property to 0 and the property to an empty string. + The method removes all key/value pairs from the and resets the and properties to their default values. The method also sets the property to 0 and the property to an empty string. @@ -242,7 +242,7 @@ You can pass a connection string in the constructor, or you can set the instance, sets some of its properties, and then tries to determine whether various keys exist within the object by calling the method. + The following example creates an instance, sets some of its properties, and then tries to determine whether various keys exist within the object by calling the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OdbcConnectionStringBuilder.ContainsKey/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnectionStringBuilder/ContainsKey/source.vb" id="Snippet1"::: @@ -463,12 +463,12 @@ The order of the values in the is the same method returns a value that indicates its success, it is not required to look for the existence of a key before trying to remove the key/value pair from the instance. + Because the method returns a value that indicates its success, it is not required to look for the existence of a key before trying to remove the key/value pair from the instance. ## Examples - The following example creates an instance and demonstrates the behavior of the method. + The following example creates an instance and demonstrates the behavior of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OdbcConnectionStringBuilder.Remove/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnectionStringBuilder/Remove/source.vb" id="Snippet1"::: @@ -527,12 +527,12 @@ The order of the values in the is the same method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because does not raise an exception when you pass in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key places the value null (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because does not raise an exception when you pass in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key places the value null (`Nothing` in Visual Basic) in the `value` parameter. ## Examples - The following example demonstrates the behavior of the method. + The following example demonstrates the behavior of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OdbcConnectionStringBuilder.TryGetValue/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnectionStringBuilder/TryGetValue/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Odbc/OdbcDataAdapter.xml b/xml/System.Data.Odbc/OdbcDataAdapter.xml index 6e0d9bc8cf0..118dd5d163a 100644 --- a/xml/System.Data.Odbc/OdbcDataAdapter.xml +++ b/xml/System.Data.Odbc/OdbcDataAdapter.xml @@ -90,17 +90,17 @@ serves as a bridge between a `DataSet` and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. + The serves as a bridge between a `DataSet` and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. - When the fills a , it creates the required tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + When the fills a , it creates the required tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). > [!NOTE] > When you call the `Fill` method on a data source that does not have a primary key column, the tries to promote the unique constraint column to the primary key. In the process, the marks the unique constraint as not nullable. This behavior works unless there is a null value in the unique constraint column. If there is a null value, the `Fill` method fails with a constraint violation. To avoid this situation, do not allow null values in the unique constraint column. > [!NOTE] -> Due to the limitations of native ODBC drivers, only one is ever returned when you call . This is true even when executing SQL batch statements from which multiple objects would be expected. +> Due to the limitations of native ODBC drivers, only one is ever returned when you call . This is true even when executing SQL batch statements from which multiple objects would be expected. - The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. + The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. @@ -153,8 +153,8 @@ |Properties|Default value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -206,8 +206,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -453,14 +453,14 @@ property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . + When the property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.DeleteCommand/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source.vb" id="Snippet1"::: @@ -544,9 +544,9 @@ property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . + When the property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] > If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. @@ -554,7 +554,7 @@ ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.InsertCommand/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source1.vb" id="Snippet1"::: @@ -652,11 +652,11 @@ , there are two events that occur per data row updated. The order of execution is as follows: + When you use , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -664,9 +664,9 @@ 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. ]]> @@ -701,11 +701,11 @@ , there are two events that occur per data row updated. The order of execution is as follows: + When you use , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -713,9 +713,9 @@ 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. ]]> @@ -769,14 +769,14 @@ is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - If returns no rows, no tables are added to the , and no exception is raised. + If returns no rows, no tables are added to the , and no exception is raised. ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.SelectCommand/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/SelectCommand/source.vb" id="Snippet1"::: @@ -1020,9 +1020,9 @@ is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] > If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. @@ -1030,7 +1030,7 @@ ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.UpdateCommand/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Odbc/OdbcDataReader.xml b/xml/System.Data.Odbc/OdbcDataReader.xml index 202a8fee631..77104097e0f 100644 --- a/xml/System.Data.Odbc/OdbcDataReader.xml +++ b/xml/System.Data.Odbc/OdbcDataReader.xml @@ -58,13 +58,13 @@ , you must call the method of the object, instead of directly using a constructor. + To create an , you must call the method of the object, instead of directly using a constructor. - While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . + While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . Changes made to a result set by another process or thread while data is being read may be visible to the user of the . However, the precise behavior is both driver and timing dependent. - and are the only properties that you can call after the is closed. Sometimes, you must call before you can call . + and are the only properties that you can call after the is closed. Sometimes, you must call before you can call . @@ -115,7 +115,7 @@ method when you are finished using the to use the associated for any other purpose. + You must explicitly call the method when you are finished using the to use the associated for any other purpose. > [!CAUTION] > Do not call `Close` or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). @@ -237,9 +237,9 @@ to exclude hidden fields. + Includes hidden fields. Use to exclude hidden fields. - After you execute a query that does not return rows, returns 0. + After you execute a query that does not return rows, returns 0. ]]> @@ -313,7 +313,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -363,7 +363,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -420,9 +420,9 @@ returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - If you pass a buffer that is a null value, returns the length of the field in bytes. + If you pass a buffer that is a null value, returns the length of the field in bytes. Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. @@ -476,7 +476,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -533,9 +533,9 @@ returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - If you pass a buffer that is a null value, returns the length of the field in characters. + If you pass a buffer that is a null value, returns the length of the field in characters. Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. @@ -698,7 +698,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -748,9 +748,9 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - Call to look for null values before calling this method. + Call to look for null values before calling this method. - has a maximum precision of 28. Attempting to retrieve decimal data with a larger precision will cause an exception. One solution would be to change the query to cast the decimal type to either a smaller datatype or convert to string or binary. + has a maximum precision of 28. Attempting to retrieve decimal data with a larger precision will cause an exception. One solution would be to change the query to cast the decimal type to either a smaller datatype or convert to string or binary. ]]> @@ -800,7 +800,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -925,7 +925,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -975,7 +975,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1025,7 +1025,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1075,7 +1075,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1125,7 +1125,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1214,16 +1214,16 @@ performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. + performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. - is kana-width insensitive. + is kana-width insensitive. - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call one time and then assign the results to an integer variable for use within the loop. + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call one time and then assign the results to an integer variable for use within the loop. ## Examples - The following example demonstrates how to use the method. + The following example demonstrates how to use the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader.GetOrdinal/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataRecord/GetOrdinal/source.vb" id="Snippet1"::: @@ -1272,7 +1272,7 @@ method returns metadata about each column in the following order: + The method returns metadata about each column in the following order: |DataReader column|Description| |-----------------------|-----------------| @@ -1303,7 +1303,7 @@ needs the correct identification of the primary keys of the table in order to work correctly. If the BaseTableName is not returned for every column in the query results, the .NET Framework Data Provider for ODBC tries to parse the SQL statement to find the table names involved in the query. This works with UPDATE, INSERT, DELETE and simple SELECT statements, but not with stored procedures or SELECT statements based on joins. If some or all the schema information is missing from this table, the will not work correctly, because it has insufficient schema information to automatically generate the correct INSERT, UPDATE, or DELETE statements. - To make sure that metadata columns return the correct information, you must call with the behavior parameter set to KeyInfo. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. + To make sure that metadata columns return the correct information, you must call with the behavior parameter set to KeyInfo. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. When you use ODBC.NET to Oracle via the ODBC driver, aliased key columns are not recognized as keys. This affects the IsKey and IsUnique columns in the schema table of the OdbcDataReader. It also affects the OdbcCommandBuilder's ability to generate updating logic. Consider not using an alias for a primary key column. @@ -1358,7 +1358,7 @@ ## Remarks Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported, the method call fails. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1485,7 +1485,7 @@ method provides an efficient means for retrieving all columns, instead of retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, instead of retrieving each column individually. You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns that are contained in the resulting row. @@ -1569,7 +1569,7 @@ and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> @@ -1617,7 +1617,7 @@ , , and so on). + To avoid raising an error, call this method to look for null column values before calling the typed Get methods (for example, , , and so on). ]]> @@ -1806,9 +1806,9 @@ is before the first record. Therefore, you must call to start accessing any data. + The default position of the is before the first record. Therefore, you must call to start accessing any data. - While the is being used, the associated is busy serving it until you call . + While the is being used, the associated is busy serving it until you call . @@ -1859,9 +1859,9 @@ ## Remarks The property is not set until all rows are read and you close the . - The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of will be 2. + The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of will be 2. - and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> diff --git a/xml/System.Data.Odbc/OdbcException.xml b/xml/System.Data.Odbc/OdbcException.xml index a1943c05e5b..c964493ce7f 100644 --- a/xml/System.Data.Odbc/OdbcException.xml +++ b/xml/System.Data.Odbc/OdbcException.xml @@ -158,7 +158,7 @@ sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. + sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. ]]> @@ -217,12 +217,12 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ## Examples - The following example displays the , , and properties of the first within the collection. + The following example displays the , , and properties of the first within the collection. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcException.Source/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcException/Source/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml b/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml index f23676f1eaa..0e7d919cd1d 100644 --- a/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml +++ b/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml @@ -100,7 +100,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> diff --git a/xml/System.Data.Odbc/OdbcParameter.xml b/xml/System.Data.Odbc/OdbcParameter.xml index fa4c0a8a9ab..4da520ff874 100644 --- a/xml/System.Data.Odbc/OdbcParameter.xml +++ b/xml/System.Data.Odbc/OdbcParameter.xml @@ -229,7 +229,7 @@ OleDbDataReader reader = command.ExecuteReader(); Parameter = new OdbcParameter("@pname", Convert.ToInt32(0)); ``` - If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. + If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. ]]> @@ -380,7 +380,7 @@ Parameter = new OdbcParameter("@pname", Convert.ToInt32(0)); and displays the . + The following example creates an and displays the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcParameter.OdbcParameter4/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcParameter/.ctor/source4.vb" id="Snippet1"::: @@ -444,7 +444,7 @@ Parameter = new OdbcParameter("@pname", Convert.ToInt32(0)); and displays the . + The following example creates an and displays the . ```vb Public Sub CreateOdbcParameter() @@ -517,9 +517,9 @@ public void CreateOdbcParameter() and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . - For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). > [!NOTE] > is not supported by the Microsoft .NET Framework Data Provider for ODBC. @@ -584,7 +584,7 @@ public void CreateOdbcParameter() ## Remarks If the is `Output`, and execution of the associated does not return a value, the will contain a null value. Null values are handled using the class. - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or `Dispose` on the . + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or `Dispose` on the . @@ -741,7 +741,7 @@ public void CreateOdbcParameter() and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -871,7 +871,7 @@ public void CreateMyProc(OdbcConnection connection) ## Remarks Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. - The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. + The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. > [!NOTE] > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. @@ -932,9 +932,9 @@ public void CreateOdbcParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . - Calling resets to its default value (String). + Calling resets to its default value (String). ]]> @@ -968,7 +968,7 @@ public void CreateOdbcParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -1016,7 +1016,7 @@ public void CreateOdbcParameter() The effect of setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, or truncate or round data. - The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. + The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. When using SQL Server Native Client 10 (or later) to bind a parameter whose type is Decimal, Numeric, VarNumeric, DBDate, or DBTimeStamp, you must manually specify an appropriate Scale value. @@ -1097,16 +1097,16 @@ public void CreateOdbcParameter() ## Remarks The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, `Size` describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, `Size` could be used to limit the amount of data sent to the server to the first one hundred characters. For bidirectional and output parameters, and return values, you must set the value of `Size`. This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, `Size` does not contain inferred value after statement execution. + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, `Size` does not contain inferred value after statement execution. > [!NOTE] -> For an `OdbcParameter` with a of `ParameterDirection.Output`, `ParameterDirection.InputOutput`, or `ParameterDirection.ReturnValue`, an exception is thrown when the command is executed if the size of the value returned by the data source exceeds the specified `Size` of the . +> For an `OdbcParameter` with a of `ParameterDirection.Output`, `ParameterDirection.InputOutput`, or `ParameterDirection.ReturnValue`, an exception is thrown when the command is executed if the size of the value returned by the data source exceeds the specified `Size` of the . For fixed-length data types, the value of `Size` is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. @@ -1181,7 +1181,7 @@ public void CreateOdbcParameter() is set to anything other than an empty string, the value of the parameter is retrieved from the column with the `SourceColumn` name. If is set to `Input`, the value is taken from the . If `Direction` is set to `Output`, the value is taken from the data source. A `Direction` of `InputOutput` is a combination of both. + When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the `SourceColumn` name. If is set to `Input`, the value is taken from the . If `Direction` is set to `Output`, the value is taken from the data source. A `Direction` of `InputOutput` is a combination of both. For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1238,16 +1238,16 @@ public void CreateOdbcParameter() is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following example. In this query expression, "FieldName" represents the name of the field: + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following example. In this query expression, "FieldName" represents the name of the field: ```tsql ((@IsNull_FieldName = 1 AND FieldName IS NULL) OR (FieldName = @Original_FieldName)) ``` - If for the field is false, generates the following WHERE clause: + If for the field is false, generates the following WHERE clause: ```tsql FieldName = @OriginalFieldName @@ -1300,9 +1300,9 @@ FieldName = @OriginalFieldName during an operation to determine whether the parameter value is set to Current or Original. This allows primary keys to be updated. + The `SourceVersion` is used by during an operation to determine whether the parameter value is set to Current or Original. This allows primary keys to be updated. - This property is set to the version of the used by either the `Item` property (`DataRow` indexer), or the method. + This property is set to the version of the used by either the `Item` property (`DataRow` indexer), or the method. @@ -1453,11 +1453,11 @@ public void CreateOdbcParameter() ## Remarks For input parameters, the value is bound to the that is sent to the server. For output and return-value parameters, the value is set on completion of the and after the is closed. - When you send a null parameter value to the server, the user must specify , not null. A null value in the system is an empty object that has no value. is used to represent null values. If the parameter is used to call a stored procedure with parameters that have default values, setting to null causes the default value to be used. + When you send a null parameter value to the server, the user must specify , not null. A null value in the system is an empty object that has no value. is used to represent null values. If the parameter is used to call a stored procedure with parameters that have default values, setting to null causes the default value to be used. If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - Both the and properties can be inferred by setting . If applicable, the size, precision, and scale is also inferred from when the parameterized statement is executed. However, inferred values are not exposed to the user. + Both the and properties can be inferred by setting . If applicable, the size, precision, and scale is also inferred from when the parameterized statement is executed. However, inferred values are not exposed to the user. The property is overwritten by the `Update` method. diff --git a/xml/System.Data.Odbc/OdbcParameterCollection.xml b/xml/System.Data.Odbc/OdbcParameterCollection.xml index c4463453687..1e57c0092a8 100644 --- a/xml/System.Data.Odbc/OdbcParameterCollection.xml +++ b/xml/System.Data.Odbc/OdbcParameterCollection.xml @@ -240,7 +240,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); to the collection. + The following example adds an to the collection. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcParameterCollection.Add2/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcParameterCollection/Add/source.vb" id="Snippet1"::: @@ -307,7 +307,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integer value to an type when the value is zero. If you don't perform this conversion, the compiler will assume you are attempting to call the overload. + Use caution when using this overload of the method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integer value to an type when the value is zero. If you don't perform this conversion, the compiler will assume you are attempting to call the overload. ]]> @@ -418,7 +418,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); to the collection. + The following example adds an to the collection. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcParameterCollection.Add4/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcParameterCollection/Add/source2.vb" id="Snippet1"::: @@ -707,7 +707,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. + The following example searches for an with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcParameterCollection.this1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcParameterCollection/Contains/source.vb" id="Snippet1"::: @@ -1352,7 +1352,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. + The following example searches for an with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcParameterCollection.this1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcParameterCollection/Contains/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Odbc/OdbcPermission.xml b/xml/System.Data.Odbc/OdbcPermission.xml index c71c99e14ae..5a474e21973 100644 --- a/xml/System.Data.Odbc/OdbcPermission.xml +++ b/xml/System.Data.Odbc/OdbcPermission.xml @@ -197,7 +197,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> diff --git a/xml/System.Data.Odbc/OdbcRowUpdatedEventArgs.xml b/xml/System.Data.Odbc/OdbcRowUpdatedEventArgs.xml index 41e64d22c1c..56dce561244 100644 --- a/xml/System.Data.Odbc/OdbcRowUpdatedEventArgs.xml +++ b/xml/System.Data.Odbc/OdbcRowUpdatedEventArgs.xml @@ -36,27 +36,27 @@ Provides data for the event. - event is raised when an update to a row is completed. - - When using the `Update` method, there are two events that occur for each data row updated: and . The order of execution for an is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + event is raised when an update to a row is completed. + + When using the `Update` method, there are two events that occur for each data row updated: and . The order of execution for an is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> diff --git a/xml/System.Data.Odbc/OdbcRowUpdatingEventArgs.xml b/xml/System.Data.Odbc/OdbcRowUpdatingEventArgs.xml index b5152d5f31e..74b950f9510 100644 --- a/xml/System.Data.Odbc/OdbcRowUpdatingEventArgs.xml +++ b/xml/System.Data.Odbc/OdbcRowUpdatingEventArgs.xml @@ -42,27 +42,27 @@ Provides data for the event. - event is raised before an update to a row. - - When using the `Update` method, there are two events that occur for each data row updated: and . The order of execution for an update operation is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + event is raised before an update to a row. + + When using the `Update` method, there are two events that occur for each data row updated: and . The order of execution for an update operation is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> diff --git a/xml/System.Data.Odbc/OdbcTransaction.xml b/xml/System.Data.Odbc/OdbcTransaction.xml index 2c4ed818897..04427456d0d 100644 --- a/xml/System.Data.Odbc/OdbcTransaction.xml +++ b/xml/System.Data.Odbc/OdbcTransaction.xml @@ -55,19 +55,19 @@ Represents an SQL transaction to be made at a data source. This class cannot be inherited. - object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction) are performed on the object. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. - + object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction) are performed on the object. + + + +## Examples + The following example creates an and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcTransaction/Overview/source.vb" id="Snippet1"::: + ]]> @@ -108,21 +108,21 @@ Commits the database transaction. - and an . It also demonstrates how to use the , , and methods. - + and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing Transactions @@ -153,11 +153,11 @@ Gets the object associated with the transaction, or if the transaction is no longer valid. The object associated with the transaction. - . - + . + ]]> Performing Transactions @@ -250,11 +250,11 @@ Specifies the for this transaction. The for this transaction. The default depends on the underlying ODBC driver. - applies to the whole transaction. - + applies to the whole transaction. + ]]> Performing Transactions @@ -293,26 +293,26 @@ Rolls back a transaction from a pending state. - has been called, but before is called). The transaction will be rolled back in the event it is disposed before `Commit` or `Rollback` is called. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. - + has been called, but before is called). The transaction will be rolled back in the event it is disposed before `Commit` or `Rollback` is called. + + + +## Examples + The following example creates an and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/BeginTransaction/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing Transactions diff --git a/xml/System.Data.OleDb/OleDbCommand.xml b/xml/System.Data.OleDb/OleDbCommand.xml index f6fa89bf179..63f1f224f07 100644 --- a/xml/System.Data.OleDb/OleDbCommand.xml +++ b/xml/System.Data.OleDb/OleDbCommand.xml @@ -94,9 +94,9 @@ |Item|Description| |----------|-----------------| -||Executes commands that return rows. may not have the effect that you want if used to execute commands such as SQL SET statements.| -||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| -||Retrieves a single value, for example, an aggregate value from a database.| +||Executes commands that return rows. may not have the effect that you want if used to execute commands such as SQL SET statements.| +||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| +||Retrieves a single value, for example, an aggregate value from a database.| You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. @@ -155,10 +155,10 @@ |Properties|Initial Value| |----------------|-------------------| -||empty string ("")| -||30| -||`Text`| -||null| +||empty string ("")| +||30| +||`Text`| +||null| @@ -206,10 +206,10 @@ |Properties|Initial Value| |----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||null| +||`cmdText`| +||30| +||`Text`| +||null| @@ -259,10 +259,10 @@ |Properties|Initial Value| |----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||A new that is the value for the `connection` parameter.| +||`cmdText`| +||30| +||`Text`| +||A new that is the value for the `connection` parameter.| You can change the value for any of these parameters by setting the related property. @@ -316,10 +316,10 @@ |Properties|Initial Value| |----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||A new that is the value for the `connection` parameter.| +||`cmdText`| +||30| +||`Text`| +||A new that is the value for the `connection` parameter.| You can change the value for any of these parameters by setting the related property. @@ -481,11 +481,11 @@ ## Remarks When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods. - When is set to `TableDirect`, the property should be set to the name of the table or tables to be accessed. The user may be required to use escape character syntax if any of the named tables contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the `Execute` methods. + When is set to `TableDirect`, the property should be set to the name of the table or tables to be accessed. The user may be required to use escape character syntax if any of the named tables contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the `Execute` methods. - You cannot set the , , and properties if the current connection is performing an execute or fetch operation. + You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - The OLE DB.NET Provider does not support named parameters for passing parameters to an SQL Statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: + The OLE DB.NET Provider does not support named parameters for passing parameters to an SQL Statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: `SELECT * FROM Customers WHERE CustomerID = ?` @@ -550,7 +550,7 @@ because an attempt to execute a command will wait indefinitely. + A value of 0 indicates no limit, and should be avoided in a because an attempt to execute a command will wait indefinitely. ]]> @@ -607,9 +607,9 @@ ## Remarks When you set the property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. - The , and properties cannot be set if the current connection is performing an execute or fetch operation. + The , and properties cannot be set if the current connection is performing an execute or fetch operation. - The OLE DB .NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to Text. In this case, the question mark (?) placeholder must be used. For example: + The OLE DB .NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to Text. In this case, the question mark (?) placeholder must be used. For example: `SELECT * FROM Customers WHERE CustomerID = ?` @@ -672,9 +672,9 @@ , and properties if the current connection is performing an execute or fetch operation. + You cannot set the , and properties if the current connection is performing an execute or fetch operation. - If you set while a transaction is in progress and the property is not null, an is generated. If the property is not null and the transaction has already been committed or rolled back, is set to null. + If you set while a transaction is in progress and the property is not null, an is generated. If the property is not null and the transaction has already been committed or rolled back, is set to null. @@ -747,7 +747,7 @@ method is a strongly typed version of . + The method is a strongly typed version of . ]]> @@ -986,16 +986,16 @@ to perform catalog operations, for example, to query the structure of a database or to create database objects such as tables, or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. + You can use the to perform catalog operations, for example, to query the structure of a database or to create database objects such as tables, or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. - Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. + Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. If a rollback occurs, the return value is also -1. ## Examples - The following example creates an and then executes it using . The example is passed a string that is an SQL statement such as UPDATE, INSERT, or DELETE, and a string to use to connect to the data source. + The following example creates an and then executes it using . The example is passed a string that is an SQL statement such as UPDATE, INSERT, or DELETE, and a string to use to connect to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteNonQuery Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: @@ -1054,7 +1054,7 @@ property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . Before you close the , first close the object. You must also close the object if you plan to reuse an object. @@ -1105,9 +1105,9 @@ with the method of the object, the .NET Framework Data Provider for OLE DB performs binding using the OLE DB **IRow** interface if it is available. Otherwise, it uses the **IRowset** interface. If your SQL statement is expected to return only a single row, specifying can also improve application performance. + When you specify with the method of the object, the .NET Framework Data Provider for OLE DB performs binding using the OLE DB **IRow** interface if it is available. Otherwise, it uses the **IRowset** interface. If your SQL statement is expected to return only a single row, specifying can also improve application performance. - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . @@ -1165,9 +1165,9 @@ method to retrieve a single value, for example, an aggregate value, from a data source. This requires less code than using the method, and then performing the operations that are required to generate the single value using the data returned by an . + Use the method to retrieve a single value, for example, an aggregate value, from a data source. This requires less code than using the method, and then performing the operations that are required to generate the single value using the data returned by an . - A typical query can be formatted as in the following C# example: + A typical query can be formatted as in the following C# example: ``` CommandText = "SELECT COUNT(*) FROM region"; @@ -1177,7 +1177,7 @@ Int32 count = (Int32) ExecuteScalar(); ## Examples - The following example creates an and then executes it using . The example is passed a string that is an SQL statement that returns an aggregate result, and a string to use to connect to the data source. + The following example creates an and then executes it using . The example is passed a string that is an SQL statement that returns an aggregate result, and a string to use to connect to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteScalar/CS/mysample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: @@ -1230,7 +1230,7 @@ Int32 count = (Int32) ExecuteScalar(); when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: + The OLE DB .NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: `SELECT * FROM Customers WHERE CustomerID = ?` @@ -1290,11 +1290,11 @@ Int32 count = (Int32) ExecuteScalar(); property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. + If the property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. - Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the **Size** property to the maximum size needed. returns an error if these conditions are not met. + Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the **Size** property to the maximum size needed. returns an error if these conditions are not met. - If you call an `Execute` method after you call , any parameter value that is larger than the value specified by the **Size** property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + If you call an `Execute` method after you call , any parameter value that is larger than the value specified by the **Size** property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum **Size**. @@ -1344,7 +1344,7 @@ Int32 count = (Int32) ExecuteScalar(); is 30 seconds. + The default value of the is 30 seconds. ]]> @@ -1484,7 +1484,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For a description of this member, see . + For a description of this member, see . ]]> @@ -1623,7 +1623,7 @@ This member is an explicit interface member implementation. It can be used only value is Both unless the command is automatically generated (as with the ), in which case the default is None. + The default value is Both unless the command is automatically generated (as with the ), in which case the default is None. For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). diff --git a/xml/System.Data.OleDb/OleDbCommandBuilder.xml b/xml/System.Data.OleDb/OleDbCommandBuilder.xml index bafdb2ed413..93a1c3f167e 100644 --- a/xml/System.Data.OleDb/OleDbCommandBuilder.xml +++ b/xml/System.Data.OleDb/OleDbCommandBuilder.xml @@ -54,11 +54,11 @@ The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata is retrieved, such as after the first update, you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata is retrieved, such as after the first update, you should call the method to update the metadata. - The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. + The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. - If you call , the is disassociated from the , and the generated commands are no longer used. + If you call , the is disassociated from the , and the generated commands are no longer used. @@ -263,11 +263,11 @@ overwrites any existing parameter information for the . + overwrites any existing parameter information for the . - requires an additional call to the data source to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. + requires an additional call to the data source to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. - You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. + You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). @@ -315,11 +315,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -356,11 +356,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -398,11 +398,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -428,11 +428,11 @@ method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -469,11 +469,11 @@ method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -511,11 +511,11 @@ method for informational or troubleshooting purposes because it returns the text of the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the text of the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -631,11 +631,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -672,11 +672,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . ]]> @@ -714,11 +714,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: diff --git a/xml/System.Data.OleDb/OleDbConnection.xml b/xml/System.Data.OleDb/OleDbConnection.xml index 195763d2c3a..7cfb5685bec 100644 --- a/xml/System.Data.OleDb/OleDbConnection.xml +++ b/xml/System.Data.OleDb/OleDbConnection.xml @@ -78,7 +78,7 @@ You can open more than one DataReader on a single . If the OLE DB provider you use does not support more than one DataReader on a single connection, the provider implicitly opens an additional connection for each. - If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or **Dispose**, or by using the object within a `Using` statement. + If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or **Dispose**, or by using the object within a `Using` statement. > [!NOTE] > To deploy high-performance applications, you must use connection pooling. When you use the .NET Framework Data Provider for OLE DB, you do not have to enable connection pooling because the provider manages this automatically. For more information about how to use connection pooling with the .NET Framework Data Provider for OLE DB, see [OLE DB, ODBC, and Oracle Connection Pooling](/dotnet/framework/data/adonet/ole-db-odbc-and-oracle-connection-pooling). @@ -95,7 +95,7 @@ ## Examples - The following example creates an and an . The is opened and set as the for the . The example then calls and closes the connection. To accomplish this, is passed a connection string and a query string that is an SQL INSERT statement. + The following example creates an and an . The is opened and set as the for the . The example then calls and closes the connection. To accomplish this, is passed a connection string and a query string that is an SQL INSERT statement. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/Overview/source.vb" id="Snippet1"::: @@ -143,10 +143,10 @@ |Properties|Initial value| |----------------|-------------------| -||empty string ("")| -||15| -||empty string ("")| -||empty string ("")| +||empty string ("")| +||15| +||empty string ("")| +||empty string ("")| You can change the value for these properties only by using the property. @@ -196,10 +196,10 @@ |Properties|Initial value| |----------------|-------------------| -||`connectionString`| -||15| -||empty string ("")| -||empty string ("")| +||`connectionString`| +||15| +||empty string ("")| +||empty string ("")| You can change the value for these properties only by using the property. @@ -286,12 +286,12 @@ or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. + You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. ## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. + The following example creates an and an . It also demonstrates how to use the , , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source.vb" id="Snippet1"::: @@ -335,15 +335,15 @@ or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. + You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for OLE DB transaction management model performs correctly, avoid using other transaction management models, such as those provided by the data source. > [!NOTE] -> If you do not specify an isolation level, the default isolation level for the underlying provider is used. To specify an isolation level with the method, use the overload that takes the `isolationLevel` parameter. +> If you do not specify an isolation level, the default isolation level for the underlying provider is used. To specify an isolation level with the method, use the overload that takes the `isolationLevel` parameter. ## Examples - The following example creates an and an . It also demonstrates how to use the , a , and methods. + The following example creates an and an . It also demonstrates how to use the , a , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source1.vb" id="Snippet1"::: @@ -447,12 +447,12 @@ method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. If is called while handling a event, no additional events are fired. + The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. If is called while handling a event, no additional events are fired. - An application can call more than one time. No exception is generated. + An application can call more than one time. No exception is generated. > [!CAUTION] -> Do not call or **Dispose** on an , an , or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). +> Do not call or **Dispose** on an , an , or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). ]]> @@ -527,11 +527,11 @@ is designed to match OLE DB connection string format as closely as possible with the following exceptions: + The is designed to match OLE DB connection string format as closely as possible with the following exceptions: - The "Provider = `value` " clause is required. However, you cannot use "Provider = MSDASQL" because the .NET Framework Data Provider for OLE DB does not support the OLE DB Provider for ODBC (MSDASQL). To access ODBC data sources, use the object that is in the namespace. -- Unlike ODBC or ADO, the connection string that is returned is the same as the user-set , minus security information if `Persist Security Info` is set to `false` (default). The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the `Persist Security Info` keyword to `true` (not recommended). To maintain a high level of security, it is strongly recommended that you use the `Integrated Security` keyword with `Persist Security Info` set to `false`. +- Unlike ODBC or ADO, the connection string that is returned is the same as the user-set , minus security information if `Persist Security Info` is set to `false` (default). The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the `Persist Security Info` keyword to `true` (not recommended). To maintain a high level of security, it is strongly recommended that you use the `Integrated Security` keyword with `Persist Security Info` set to `false`. You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings. @@ -547,11 +547,11 @@ For more information about connection strings, see [Using Connection String Keywords with SQL Server Native Client](https://go.microsoft.com/fwlink/?LinkId=126696). - The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . + The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . - Resetting the on a closed connection resets all connection string values and related properties. This includes the password. For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the property is no longer set to AdventureWorks. (The Initial Catalog value of the connection string corresponds to the `Database` property.) + Resetting the on a closed connection resets all connection string values and related properties. This includes the password. For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the property is no longer set to AdventureWorks. (The Initial Catalog value of the connection string corresponds to the `Database` property.) - A preliminary validation of the connection string is performed when the property is set. If values for the `Provider`, `Connect Timeout`, `Persist Security Info`, or `OLE DB Services` are included in the string, these values are checked. When an application calls the method, the connection string is fully validated. If the connection string contains invalid or unsupported properties, a run-time exception, such as , is generated. + A preliminary validation of the connection string is performed when the property is set. If values for the `Provider`, `Connect Timeout`, `Persist Security Info`, or `OLE DB Services` are included in the string, these values are checked. When an application calls the method, the connection string is fully validated. If the connection string contains invalid or unsupported properties, a run-time exception, such as , is generated. > [!CAUTION] > It is possible to supply connection information for an in a Universal Data Link (UDL) file; however you should avoid doing so. UDL files are not encrypted and expose connection string information in clear text. Because a UDL file is an external file-based resource to your application, it cannot be secured using the .NET Framework. @@ -631,7 +631,7 @@ because an attempt to connect will wait indefinitely. + A value of 0 indicates no limit, and should be avoided in a because an attempt to connect will wait indefinitely. @@ -751,7 +751,7 @@ property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. @@ -892,11 +892,11 @@ method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). - You can continue to enlist in an existing distributed transaction using the method if auto-enlistment is disabled. Enlisting in an existing distributed transaction makes sure that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + You can continue to enlist in an existing distributed transaction using the method if auto-enlistment is disabled. Enlisting in an existing distributed transaction makes sure that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). - returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You won't receive notice that the local transaction was rolled back and are responsible for managing any local transactions not started using . + returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You won't receive notice that the local transaction was rolled back and are responsible for managing any local transactions not started using . ]]> @@ -934,7 +934,7 @@ method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). ]]> @@ -1217,7 +1217,7 @@ The draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to the data source. You can open more than one DataReader on a single . If the OLEDB provider you use does not support more than one active DataReader on a single connection, the OLEDB provider implicitly opens an additional connection for each. > [!NOTE] -> If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or **Dispose**, or using the connection within a `Using` statement. +> If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling or **Dispose**, or using the connection within a `Using` statement. ]]> @@ -1310,15 +1310,15 @@ The following must occur before the pool is finally disposed: -1. Call to return the connection object to the pool. +1. Call to return the connection object to the pool. 2. Allow each connection object to time out of the pool. -3. Call . +3. Call . 4. Invoke garbage collection. - Conversely, if you call on all active connections, and invoke garbage collection, but do not call , the resources reserved for the pooled objects will remain available. + Conversely, if you call on all active connections, and invoke garbage collection, but do not call , the resources reserved for the pooled objects will remain available. @@ -1367,7 +1367,7 @@ , the property will continue to return `Open`. If you are working with an OLE DB Provider that supports polling for this information on a live connection, calling the method and then checking the property will tell you that the connection is no longer open. The method relies on functionality in the OLE DB Provider to verify the current state of the connection. To determine if your OLE DB Provider supports this functionality, check the provider's documentation for information on DBPROP_CONNECTIONSTATUS. + Some OLE DB providers can check the current state of the connection. For example, if the database server has recycled since you opened your , the property will continue to return `Open`. If you are working with an OLE DB Provider that supports polling for this information on a live connection, calling the method and then checking the property will tell you that the connection is no longer open. The method relies on functionality in the OLE DB Provider to verify the current state of the connection. To determine if your OLE DB Provider supports this functionality, check the provider's documentation for information on DBPROP_CONNECTIONSTATUS. ]]> @@ -1419,7 +1419,7 @@ property maps to the OLE DB DBPROP_DBMSVER property. If is not supported by the underlying OLE DB provider, an empty string is returned. + The property maps to the OLE DB DBPROP_DBMSVER property. If is not supported by the underlying OLE DB provider, an empty string is returned. The version is of the form *##.##.####*, where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The provider must render the product version in this form but can also append the product-specific version - for example, "04.01.0000 Rdb 4.1". The string is of the form *major.minor.build*, where major and minor are exactly two digits and build is exactly four digits. @@ -1488,8 +1488,8 @@ The following are allowed state changes: -- From `Closed` to `Open`, using the method of the object. -- From `Open` to `Closed`, using either the method or the **Dispose** method of the object. +- From `Closed` to `Open`, using the method of the object. +- From `Open` to `Closed`, using either the method or the **Dispose** method of the object. ]]> diff --git a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml index 794f781f21a..4c63a15d089 100644 --- a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml +++ b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml @@ -66,11 +66,11 @@ |Key|Property|Default value| |---------|--------------|-------------------| -|File Name||""| -|Provider||""| -|Data Source||""| -|Persist Security Info||False| -|OLE DB Services||-13| +|File Name||""| +|Provider||""| +|Data Source||""| +|Persist Security Info||False| +|OLE DB Services||-13| The property handles attempts to insert malicious entries. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair: @@ -210,7 +210,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal method removes all key/value pairs from the , and resets all corresponding properties to their default values. This includes setting the property to 0, and setting the property to an empty string. + The method removes all key/value pairs from the , and resets all corresponding properties to their default values. This includes setting the property to 0, and setting the property to an empty string. ]]> @@ -250,12 +250,12 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property may implicitly fill in appropriate key/value pairs for the provider, the method does not return `true` for implicitly provided keys. This method returns `true` only for explicitly provided keys. + Although setting the property may implicitly fill in appropriate key/value pairs for the provider, the method does not return `true` for implicitly provided keys. This method returns `true` only for explicitly provided keys. ## Examples - The following example creates an instance, sets some of its properties, and then tries to determine whether various keys exist within the object by calling the method. + The following example creates an instance, sets some of its properties, and then tries to determine whether various keys exist within the object by calling the method. ]]> @@ -307,7 +307,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal ## Examples - The following example console application creates a new instance, and then sets the and properties. Finally, the example creates a new instance, and uses that object to connect to the indicated data store. + The following example console application creates a new instance, and then sets the and properties. Finally, the example creates a new instance, and uses that object to connect to the indicated data store. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.DataSource/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/DataSource/source.vb" id="Snippet1"::: @@ -680,12 +680,12 @@ The order of the values in the is unspecif method returns a value that indicates its success, it is not required to look for the existence of a key before trying to remove the key/value pair from the instance. + Because the method returns a value that indicates its success, it is not required to look for the existence of a key before trying to remove the key/value pair from the instance. ## Examples - The following example creates a and demonstrates the behavior of the method. + The following example creates a and demonstrates the behavior of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.Remove/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/Remove/source.vb" id="Snippet1"::: @@ -744,12 +744,12 @@ The order of the values in the is unspecif method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. ## Examples - The following example demonstrates the behavior of the method. + The following example demonstrates the behavior of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.TryGetValue/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/TryGetValue/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.OleDb/OleDbDataAdapter.xml b/xml/System.Data.OleDb/OleDbDataAdapter.xml index 278f629ced2..6720c7dcc28 100644 --- a/xml/System.Data.OleDb/OleDbDataAdapter.xml +++ b/xml/System.Data.OleDb/OleDbDataAdapter.xml @@ -93,13 +93,13 @@ serves as a bridge between a and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. + The serves as a bridge between a and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. - When the fills a , it will create the appropriate tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + When the fills a , it will create the appropriate tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). Note that some OLE DB providers, including the MSDataShape provider, do not return base table or primary key information. Therefore, the cannot correctly set the property on any created . In these cases you should explicitly specify primary keys for tables in the . - The also includes the , , , , and properties to facilitate the loading and updating of data. + The also includes the , , , , and properties to facilitate the loading and updating of data. When you create an instance of , properties are set to their initial values. For a list of these values, see the constructor. @@ -154,8 +154,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -207,8 +207,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -256,14 +256,14 @@ opens and closes an if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call or **Dispose** to close it. + This implementation of the opens and closes an if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call or **Dispose** to close it. When you create an instance of , the following read/write properties are set to the following initial values. |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of either of these properties through a separate call to the property. @@ -317,8 +317,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -476,14 +476,14 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.DeleteCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: @@ -566,15 +566,15 @@ ## Remarks The link between ActiveX Data Objects (ADO) and ADO.NET is a one-way operation in that you can copy data from ADO to the , but any updates to the data must be handled by ADO.NET. - This overload of the method does not close the input `Recordset` on completion of the operation. + This overload of the method does not close the input `Recordset` on completion of the operation. - When handling batch SQL statements that return multiple results, this implementation of and for the OLE DB.NET Framework Data Provider retrieves schema information for only the first result. + When handling batch SQL statements that return multiple results, this implementation of and for the OLE DB.NET Framework Data Provider retrieves schema information for only the first result. - The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires that the native OLE DB provider obtains required primary key information by setting the DBPROP_UNIQUEROWS property, and then determines which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the `IColumnsRowset`. Alternatively the user may explicitly set the primary key constraints on each . This makes sure that incoming records that match existing records are updated instead of appended. @@ -583,7 +583,7 @@ Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . > [!CAUTION] -> This overload of the method does not implicitly call `Close` on the ADO object when the fill operation is complete. Therefore, always call `Close` when you are finished using ADO `Recordset` or `Record` objects. This makes sure that the underlying connection to a data source is released in a timely manner, and also prevents possible access violations because of unmanaged ADO objects being reclaimed by garbage collection when existing references still exist. +> This overload of the method does not implicitly call `Close` on the ADO object when the fill operation is complete. Therefore, always call `Close` when you are finished using ADO `Recordset` or `Record` objects. This makes sure that the underlying connection to a data source is released in a timely manner, and also prevents possible access violations because of unmanaged ADO objects being reclaimed by garbage collection when existing references still exist. When you call the `TableMappings.Add` method on a `DataAdapter` and you explicitly map the source table parameter to an empty string, the dataset is successfully filled using the source table, but the dataset will be populated with nothing. For example, in the following example, `rDataSet` will be populated with nothing. @@ -675,17 +675,17 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); ## Remarks The link between ActiveX Data Objects (ADO) and ADO.NET is a one-way operation in that you can copy data from ADO to the , but any updates to the data must be handled by ADO.NET. - The method iterates through multiple results by calling the `NextRecordset` method on the `Recordset`, closing the input `Recordset` on completion of the operation. + The method iterates through multiple results by calling the `NextRecordset` method on the `Recordset`, closing the input `Recordset` on completion of the operation. - The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires the native OLE DB provider to obtain required primary key information by setting the DBPROP_UNIQUEROWS property, and then determine which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the **IColumnsRowset**. Alternatively the user may explicitly set the primary key constraints on each . This ensures that incoming records that match existing records are updated instead of appended. - If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - If the `Recordset` is closed before the starting of the operation, no error results. This is required for handling of multiple results, because queries that do not return rows are indicated by a closed `Recordset`. The just calls `NextRecordset` on the closed `Recordset` and continues processing. + If the `Recordset` is closed before the starting of the operation, no error results. This is required for handling of multiple results, because queries that do not return rows are indicated by a closed `Recordset`. The just calls `NextRecordset` on the closed `Recordset` and continues processing. If an error is encountered while populating the data set, rows added before the occurrence of the error remain in the . The rest of the operation is aborted. @@ -694,7 +694,7 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . > [!NOTE] -> This overload of the method implicitly calls `Close` on the ADO object when the fill operation is complete. +> This overload of the method implicitly calls `Close` on the ADO object when the fill operation is complete. The following example uses an to fill a using an ADO `Recordset` that is an ADO `Record` object. This example assumes that you have created an ADO `RecordSet` and `Record` object. @@ -781,9 +781,9 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. > [!NOTE] > If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. @@ -791,7 +791,7 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.InsertCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: @@ -895,11 +895,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); , there are two events that occur per data row updated. The order of execution is as follows: + When you use , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -907,9 +907,9 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. @@ -958,11 +958,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); , there are two events that occur per data row updated. The order of execution is as follows: + When you use , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -970,9 +970,9 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. @@ -1038,14 +1038,14 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - If the returns no rows, no tables are added to the , and no exception is raised. + If the returns no rows, no tables are added to the , and no exception is raised. ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.SelectCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: @@ -1293,9 +1293,9 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. > [!NOTE] > If execution of this command returns rows, these rows may be merged with the depending on how you set the property of the object. @@ -1303,7 +1303,7 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); ## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. + The following example creates an and sets the and properties. It assumes that you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.UpdateCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.OleDb/OleDbDataReader.xml b/xml/System.Data.OleDb/OleDbDataReader.xml index 1e6364113a9..c7a1ad2e1e6 100644 --- a/xml/System.Data.OleDb/OleDbDataReader.xml +++ b/xml/System.Data.OleDb/OleDbDataReader.xml @@ -67,13 +67,13 @@ , you must call the method of the object, instead of directly using a constructor. + To create an , you must call the method of the object, instead of directly using a constructor. - Before you close the , first close the object. You must also close the object if you plan to resuse an object.For example, you cannot retrieve output parameters until after you call . + Before you close the , first close the object. You must also close the object if you plan to resuse an object.For example, you cannot retrieve output parameters until after you call . Changes made to a result set by another process or thread while data is being read may be visible to the user of the . However, the precise behavior is timing dependent. - and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. + and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. @@ -124,7 +124,7 @@ method when you are through using the to use the associated for any other purpose. + You must explicitly call the method when you are through using the to use the associated for any other purpose. > [!CAUTION] > Do not call **Close** or **Dispose** on a Connection, a DataReader, or any other managed object in the **Finalize** method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a **Finalize** method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). @@ -217,9 +217,9 @@ to exclude hidden fields. + Includes hidden fields. Use to exclude hidden fields. - After executing a query that does not return rows, returns 0. + After executing a query that does not return rows, returns 0. ]]> @@ -293,7 +293,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a Boolean, or an exception is generated. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -343,7 +343,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a byte. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -400,9 +400,9 @@ returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, when the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, when the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - If you pass a buffer that is `null`, returns the length of the field in bytes. + If you pass a buffer that is `null`, returns the length of the field in bytes. No conversions are performed; therefore, the data retrieved must already be a byte array. @@ -514,9 +514,9 @@ returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, when the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, when the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - If you pass a buffer that is `null`, returns the length of the field in characters. + If you pass a buffer that is `null`, returns the length of the field in characters. No conversions are performed; therefore, the data retrieved must already be a character array. @@ -564,7 +564,7 @@ will call if the provider returns a that has a column that supports . + The will call if the provider returns a that has a column that supports . ]]> @@ -653,7 +653,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -733,7 +733,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -783,7 +783,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a double-precision floating-point number. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -908,7 +908,7 @@ ## Remarks No conversions are performed. Therefore, the data retrieved must already be a single-precision floating-point number. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -958,7 +958,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a globally unique identifier. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1008,7 +1008,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a 16-bit signed integer. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1058,7 +1058,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a 32-bit signed integer. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1108,7 +1108,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a 64-bit signed integer. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1196,16 +1196,16 @@ performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. + performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. - is kana-width insensitive. + is kana-width insensitive. - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Save time by calling one time and assigning the results to an integer variable for use within the loop. + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Save time by calling one time and assigning the results to an integer variable for use within the loop. ## Examples - The following example demonstrates how to use the method. + The following example demonstrates how to use the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataReader.GetOrdinal/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataReader/GetOrdinal/source.vb" id="Snippet1"::: @@ -1254,7 +1254,7 @@ method maps to the OLE DB **IColumnsRowset::GetColumnsRowset** method, and returns metadata about each column in the following order: + The method maps to the OLE DB **IColumnsRowset::GetColumnsRowset** method, and returns metadata about each column in the following order: |DataReader column|OLE DB column ID|Description| |-----------------------|----------------------|-----------------| @@ -1278,7 +1278,7 @@ |BaseColumnName|DBCOLUMN_BASECOLUMNNAME|The name of the column in the data store. This might be different from the column name returned in the ColumnName column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default of this column is a null value.| > [!NOTE] -> To make sure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. +> To make sure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. ]]> @@ -1328,7 +1328,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a string. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1370,7 +1370,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to look for null values before calling this method. + Call to look for null values before calling this method. ]]> @@ -1465,7 +1465,7 @@ method provides an efficient means for retrieving all columns, instead of retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, instead of retrieving each column individually. You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns that are contained in the resulting row. @@ -1549,7 +1549,7 @@ and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> @@ -1597,7 +1597,7 @@ , , and so on) to avoid raising an error. + Call this method to look for null column values before calling the typed get methods (for example, , , and so on) to avoid raising an error. ]]> @@ -1786,9 +1786,9 @@ is before the first record. Therefore, you must call to start accessing any data. + The default position of the is before the first record. Therefore, you must call to start accessing any data. - While the is being used, the associated is busy serving it until you call . + While the is being used, the associated is busy serving it until you call . @@ -1839,9 +1839,9 @@ ## Remarks The property is not set until all rows are read and you close the . - The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of is two. + The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of is two. - and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> diff --git a/xml/System.Data.OleDb/OleDbError.xml b/xml/System.Data.OleDb/OleDbError.xml index 79a4abb15d4..82a7c01a5c2 100644 --- a/xml/System.Data.OleDb/OleDbError.xml +++ b/xml/System.Data.OleDb/OleDbError.xml @@ -46,21 +46,21 @@ Collects information relevant to a warning or error returned by the data source. - is created and managed by the class, which in turn is created by the class. - - If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. - - - -## Examples - The following example displays the properties of the . - + is created and managed by the class, which in turn is created by the class. + + If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. + + + +## Examples + The following example displays the properties of the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -92,14 +92,14 @@ Gets a short description of the error. A short description of the error. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -131,14 +131,14 @@ Gets the database-specific error information. The database-specific error information. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -170,14 +170,14 @@ Gets the name of the provider that generated the error. The name of the provider that generated the error. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -209,14 +209,14 @@ Gets the five-character error code following the ANSI SQL standard for the database. The five-character error code, which identifies the source of the error, if the error can be issued from more than one place. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -249,21 +249,21 @@ Gets the complete text of the error message. The complete text of the error. - , and the stack trace. For example: - - OleDbError:UserId or Password not valid. \ - - - -## Examples - The following example displays each within the collection. - + , and the stack trace. For example: + + OleDbError:UserId or Password not valid. \ + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError.ToString Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/ToString/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbError/ToString/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data.OleDb/OleDbException.xml b/xml/System.Data.OleDb/OleDbException.xml index 0e6d58bf0f3..8cb45b7dc5d 100644 --- a/xml/System.Data.OleDb/OleDbException.xml +++ b/xml/System.Data.OleDb/OleDbException.xml @@ -52,23 +52,23 @@ The exception that is thrown when the underlying provider returns a warning or error for an OLE DB data source. This class cannot be inherited. - always contains at least one instance of . - - If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. - - For general information about handling exceptions for a .NET Framework data provider, see . - - - -## Examples - The following example generates an because of a missing data source, and then displays the exception. - + always contains at least one instance of . + + If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. + + For general information about handling exceptions for a .NET Framework data provider, see . + + + +## Examples + The following example generates an because of a missing data source, and then displays the exception. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbException Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbException/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbException/Overview/source.vb" id="Snippet1"::: + ]]> @@ -140,21 +140,21 @@ Gets a collection of one or more objects that give detailed information about exceptions generated by the .NET Framework Data Provider for OLE DB. The collected instances of the class. - class always contains at least one instance of the class. - - This is a wrapper for the collection. - - - -## Examples - The following example displays each within the collection. - + class always contains at least one instance of the class. + + This is a wrapper for the collection. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbError.Message Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbErrorCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbErrorCollection/Overview/source.vb" id="Snippet1"::: + ]]> Handling and throwing exceptions in .NET @@ -200,11 +200,11 @@ The that contains contextual information about the source or destination. This member overrides . - sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. - + sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. + ]]> The parameter is a null reference ( in Visual Basic). diff --git a/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml b/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml index 69d17290f03..e96e21869d5 100644 --- a/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml +++ b/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml @@ -78,7 +78,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> @@ -139,7 +139,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> @@ -180,7 +180,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> diff --git a/xml/System.Data.OleDb/OleDbParameter.xml b/xml/System.Data.OleDb/OleDbParameter.xml index 3ddcbab66f6..c0529a79576 100644 --- a/xml/System.Data.OleDb/OleDbParameter.xml +++ b/xml/System.Data.OleDb/OleDbParameter.xml @@ -179,7 +179,7 @@ OleDbDataReader reader = command.ExecuteReader(); and are inferred from the value of the `dataType` parameter. + The data type, and if appropriate, and are inferred from the value of the `dataType` parameter. @@ -232,7 +232,7 @@ OleDbDataReader reader = command.ExecuteReader(); Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); ``` - If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. + If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. @@ -280,7 +280,7 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); is inferred from the value of the `dataType` parameter if it is not explicitly set in the `size` parameter. + The is inferred from the value of the `dataType` parameter if it is not explicitly set in the `size` parameter. @@ -331,7 +331,7 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); is inferred from the value of the `dataType` parameter if it is not explicitly set in the `size` parameter. + The is inferred from the value of the `dataType` parameter if it is not explicitly set in the `size` parameter. @@ -401,12 +401,12 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); and are inferred from the value of the `dataType` parameter if they are not explicitly set in the `size` and `precision` parameters. + The and are inferred from the value of the `dataType` parameter if they are not explicitly set in the `size` and `precision` parameters. ## Examples - The following example creates an and displays the . + The following example creates an and displays the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbParameter.OleDbParameter4 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbParameter/.ctor/source4.vb" id="Snippet1"::: @@ -470,12 +470,12 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); and are inferred from the value of the `dataType` parameter if they are not explicitly set in the `size` and `precision` parameters. + The and are inferred from the value of the `dataType` parameter if they are not explicitly set in the `size` and `precision` parameters. ## Examples - The following example creates an and displays the . + The following example creates an and displays the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbParameter.OleDbParameter4 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbParameter/.ctor/source4.vb" id="Snippet1"::: @@ -538,9 +538,9 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . - For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -606,7 +606,7 @@ Parameter = new OleDbParameter("@pname", Convert.ToInt32(0)); ## Remarks If the is output, and execution of the associated does not return a value, the contains a null value. - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or **Dispose** on the . + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call or **Dispose** on the . @@ -763,7 +763,7 @@ public void CreateOleDbParameter() and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -890,7 +890,7 @@ public void CreateOleDbParameter() ## Remarks The property is only used for decimal and numeric input parameters. - The property should be set only for `Decimal` and `Numeric` parameters prior to calling the method of the . + The property should be set only for `Decimal` and `Numeric` parameters prior to calling the method of the . Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. @@ -900,7 +900,7 @@ public void CreateOleDbParameter() > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. > [!NOTE] -> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. +> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. @@ -958,7 +958,7 @@ public void CreateOleDbParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -995,7 +995,7 @@ public void CreateOleDbParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -1046,7 +1046,7 @@ public void CreateOleDbParameter() property is only used for decimal and numeric input parameters before calling the method of the and to specify numeric output parameters. + The property is only used for decimal and numeric input parameters before calling the method of the and to specify numeric output parameters. Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. @@ -1056,7 +1056,7 @@ public void CreateOleDbParameter() > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. > [!NOTE] -> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. +> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. @@ -1133,17 +1133,17 @@ public void CreateOleDbParameter() ## Remarks The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. - For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first 100 characters. + For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first 100 characters. - For bidirectional and output parameters, and return values, you must set the value of . This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. + For bidirectional and output parameters, and return values, you must set the value of . This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain the inferred value after statement execution. + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain the inferred value after statement execution. - For fixed-length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. + For fixed-length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. - If the size of the value supplied for an exceeds the specified , the of the contains the specified value, truncated to the size of the . + If the size of the value supplied for an exceeds the specified , the of the contains the specified value, truncated to the size of the . @@ -1224,7 +1224,7 @@ public void CreateOleDbParameter() is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. + When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1281,16 +1281,16 @@ public void CreateOleDbParameter() is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): ```tsql ((@IsNull_FieldName = 1 AND FieldName IS NULL) OR (FieldName = @Original_FieldName)) ``` - If for the field is false, generates the following WHERE clause: + If for the field is false, generates the following WHERE clause: ```tsql FieldName = @OriginalFieldName @@ -1347,7 +1347,7 @@ FieldName = @OriginalFieldName during an update operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the property, or the method of the object. + Used by during an update operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the property, or the method of the object. @@ -1504,7 +1504,7 @@ public void CreateOleDbParameter() If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - Both the and properties can be inferred by setting the Value. + Both the and properties can be inferred by setting the Value. The property is overwritten by the Update method of . diff --git a/xml/System.Data.OleDb/OleDbParameterCollection.xml b/xml/System.Data.OleDb/OleDbParameterCollection.xml index 30eb7fa44b5..57c64ed8df1 100644 --- a/xml/System.Data.OleDb/OleDbParameterCollection.xml +++ b/xml/System.Data.OleDb/OleDbParameterCollection.xml @@ -309,7 +309,7 @@ method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the value to an type when the value is zero.If you don't perform this conversion, the compiler will assume you are attempting to call the overload. + Use caution when using this overload of the method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the value to an type when the value is zero.If you don't perform this conversion, the compiler will assume you are attempting to call the overload. ]]> @@ -1344,7 +1344,7 @@ with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. + The following example searches for an with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbParameterCollection.this1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbParameterCollection/Item/source1.vb" id="Snippet1"::: diff --git a/xml/System.Data.OleDb/OleDbPermission.xml b/xml/System.Data.OleDb/OleDbPermission.xml index d8733494615..47824aed912 100644 --- a/xml/System.Data.OleDb/OleDbPermission.xml +++ b/xml/System.Data.OleDb/OleDbPermission.xml @@ -190,7 +190,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> diff --git a/xml/System.Data.OleDb/OleDbRowUpdatedEventArgs.xml b/xml/System.Data.OleDb/OleDbRowUpdatedEventArgs.xml index 8413a6e8991..2bdcc2cf7f2 100644 --- a/xml/System.Data.OleDb/OleDbRowUpdatedEventArgs.xml +++ b/xml/System.Data.OleDb/OleDbRowUpdatedEventArgs.xml @@ -41,27 +41,27 @@ Provides data for the event. - event is raised when an to a row is completed. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + event is raised when an to a row is completed. + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> diff --git a/xml/System.Data.OleDb/OleDbRowUpdatingEventArgs.xml b/xml/System.Data.OleDb/OleDbRowUpdatingEventArgs.xml index a0134d5fba0..fb87109f9d4 100644 --- a/xml/System.Data.OleDb/OleDbRowUpdatingEventArgs.xml +++ b/xml/System.Data.OleDb/OleDbRowUpdatingEventArgs.xml @@ -41,27 +41,27 @@ Provides data for the event. - event is raised before an to a row. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + event is raised before an to a row. + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to FirstReturnedRecord, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> diff --git a/xml/System.Data.OleDb/OleDbSchemaGuid.xml b/xml/System.Data.OleDb/OleDbSchemaGuid.xml index 30a3650fc31..d46492bef54 100644 --- a/xml/System.Data.OleDb/OleDbSchemaGuid.xml +++ b/xml/System.Data.OleDb/OleDbSchemaGuid.xml @@ -35,14 +35,14 @@ Returns the type of schema table specified by the method. - class maps to an OLE DB schema rowset. - + class maps to an OLE DB schema rowset. + > [!NOTE] -> Some members of the class, (such as schema) may not be supported by your OLE DB provider. Refer to your database documentation to determine whether you can retrieve this schema information by querying the system tables of your database. - +> Some members of the class, (such as schema) may not be supported by your OLE DB provider. Refer to your database documentation to determine whether you can retrieve this schema information by querying the system tables of your database. + ]]> @@ -94,17 +94,17 @@ Returns the assertions defined in the catalog that is owned by a given user. - maps to the OLE DB ASSERTIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB ASSERTIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -133,15 +133,15 @@ Returns the physical attributes associated with catalogs accessible from the data source. Returns the assertions defined in the catalog that is owned by a given user. - maps to the OLE DB CATALOGS rowset and returns the following restriction column. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CATALOG_NAME|`string`|Catalog name. Cannot be a null value.| - + maps to the OLE DB CATALOGS rowset and returns the following restriction column. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CATALOG_NAME|`string`|Catalog name. Cannot be a null value.| + ]]> @@ -170,17 +170,17 @@ Returns the character sets defined in the catalog that is accessible to a given user. - maps to the OLE DB CHARACTER_SETS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CHARACTER_SET_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CHARACTER_SET_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CHARACTER_SET_NAME|`string`|Character set name.| - + maps to the OLE DB CHARACTER_SETS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CHARACTER_SET_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CHARACTER_SET_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CHARACTER_SET_NAME|`string`|Character set name.| + ]]> @@ -209,17 +209,17 @@ Returns the check constraints defined in the catalog that is owned by a given user. - maps to the OLE DB CHECK_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB CHECK_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -248,17 +248,17 @@ Returns the check constraints defined in the catalog that is owned by a given user. - maps to the OLE DB CHECK_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB CHECK_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -287,17 +287,17 @@ Returns the character collations defined in the catalog that is accessible to a given user. - maps to the OLE DB COLLATIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|COLLATION_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|COLLATION_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|COLLATION_NAME|`string`|Collation name.| - + maps to the OLE DB COLLATIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|COLLATION_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|COLLATION_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|COLLATION_NAME|`string`|Collation name.| + ]]> @@ -326,18 +326,18 @@ Returns the columns defined in the catalog that are dependent on a domain defined in the catalog and owned by a given user. - maps to the OLE DB COLUMN_DOMAIN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|DOMAIN_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|DOMAIN_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|DOMAIN_NAME|`string`|View name.| -|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.)| - + maps to the OLE DB COLUMN_DOMAIN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|DOMAIN_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|DOMAIN_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|DOMAIN_NAME|`string`|View name.| +|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.)| + ]]> @@ -366,20 +366,20 @@ Returns the privileges on columns of tables defined in the catalog that are available to or granted by a given user. - maps to the OLE DB COLUMN_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| -|GRANTOR|`string`|User that granted the privileges on the table in TABLE_NAME.| -|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| - + maps to the OLE DB COLUMN_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| +|GRANTOR|`string`|User that granted the privileges on the table in TABLE_NAME.| +|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| + ]]> @@ -408,18 +408,18 @@ Returns the columns of tables (including views) defined in the catalog that is accessible to a given user. - maps to the OLE DB COLUMNS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name. The column returned cannot contain a null value.| -|COLUMN_NAME|`string`|The name of the column; this might not be unique. If this cannot be determined, a null value is returned. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.) If possible, the resulting column ID should be persistent. However, some providers do not support persistent identifiers for columns. The column ID of a base table should be invariant under views.| - + maps to the OLE DB COLUMNS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name. The column returned cannot contain a null value.| +|COLUMN_NAME|`string`|The name of the column; this might not be unique. If this cannot be determined, a null value is returned. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.) If possible, the resulting column ID should be persistent. However, some providers do not support persistent identifiers for columns. The column ID of a base table should be invariant under views.| + ]]> @@ -448,21 +448,21 @@ Returns the columns used by referential constraints, unique constraints, check constraints, and assertions, defined in the catalog and owned by a given user. - maps to the OLE DB CONSTRAINT_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB CONSTRAINT_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|COLUMN_NAME|`string`|Column name. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -491,20 +491,20 @@ Returns the tables that are used by referential constraints, unique constraints, check constraints, and assertions defined in the catalog and owned by a given user. - maps to the OLE DB CONSTRAINT_TABLE_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB CONSTRAINT_TABLE_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -532,11 +532,11 @@ Returns a list of provider-specific keywords. - is equivalent to calling the OLE DB IDBInfo::GetKeywords interface. The list of keywords is returned as a DataTable with a single column named "Keyword". Each keyword returned by the provider will be on its own row in the DataTable. - + is equivalent to calling the OLE DB IDBInfo::GetKeywords interface. The list of keywords is returned as a DataTable with a single column named "Keyword". Each keyword returned by the provider will be on its own row in the DataTable. + ]]> @@ -565,13 +565,13 @@ Returns a list of provider-specific literals used in text commands. - is equivalent to calling the OLE DB **IDBInfo::GetLiteralInfo** interface, or the ADO `Connection.OpenSchema` method with the `adSchemaDBInfoLiterals` constant. - - When using the method, if the `schema` parameter contains a value of and the `restrictions` parameter contains one or more restrictions, an is generated. - + is equivalent to calling the OLE DB **IDBInfo::GetLiteralInfo** interface, or the ADO `Connection.OpenSchema` method with the `adSchemaDBInfoLiterals` constant. + + When using the method, if the `schema` parameter contains a value of and the `restrictions` parameter contains one or more restrictions, an is generated. + ]]> @@ -600,20 +600,20 @@ Returns the foreign key columns defined in the catalog by a given user. - maps to the OLE DB FOREIGN_KEYS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|PK_TABLE_CATALOG|`string`|Catalog name in which the primary key table is defined. A null value if the provider does not support catalogs.| -|PK_TABLE_SCHEMA|`string`|Unqualified schema name in which the primary key table is defined. A null value if the provider does not support schemas.| -|PK_TABLE_NAME|`string`|Primary key table name.| -|FK_TABLE_CATALOG|`string`|Catalog name in which the foreign key table is defined. A null value if the provider does not support catalogs.| -|FK_TABLE_SCHEMA|`string`|Unqualified schema name in which the foreign key table is defined. A null value if the provider does not support schemas.| -|FK_TABLE_NAME|`string`|Foreign key table name.| - + maps to the OLE DB FOREIGN_KEYS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|PK_TABLE_CATALOG|`string`|Catalog name in which the primary key table is defined. A null value if the provider does not support catalogs.| +|PK_TABLE_SCHEMA|`string`|Unqualified schema name in which the primary key table is defined. A null value if the provider does not support schemas.| +|PK_TABLE_NAME|`string`|Primary key table name.| +|FK_TABLE_CATALOG|`string`|Catalog name in which the foreign key table is defined. A null value if the provider does not support catalogs.| +|FK_TABLE_SCHEMA|`string`|Unqualified schema name in which the foreign key table is defined. A null value if the provider does not support schemas.| +|FK_TABLE_NAME|`string`|Foreign key table name.| + ]]> @@ -642,19 +642,19 @@ Returns the indexes defined in the catalog that is owned by a given user. - maps to the OLE DB INDEXES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|INDEX_NAME|`string`|Index name.| -|TYPE|`UInt16 (Int32)`|The type of the index. One of the following:

DBPROPVAL_IT_BTREE-The index is a B+-tree.

DBPROPVAL_IT_HASH-The index is a hash file using, for example, linear or extensible hashing.

DBPROPVAL_IT_CONTENT-The index is a content index.

DBPROPVAL_IT_OTHER-The index is some other type of index.| -|TABLE_NAME|`string`|Table name.| - + maps to the OLE DB INDEXES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|INDEX_NAME|`string`|Index name.| +|TYPE|`UInt16 (Int32)`|The type of the index. One of the following:

DBPROPVAL_IT_BTREE-The index is a B+-tree.

DBPROPVAL_IT_HASH-The index is a hash file using, for example, linear or extensible hashing.

DBPROPVAL_IT_CONTENT-The index is a content index.

DBPROPVAL_IT_OTHER-The index is some other type of index.| +|TABLE_NAME|`string`|Table name.| + ]]> @@ -683,21 +683,21 @@ Returns the columns defined in the catalog that is constrained as keys by a given user. - maps to the OLE DB KEY_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| -|TABLE_CATALOG|`string`|Catalog name in which the table containing the key column is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table containing the key column is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name containing the key column.| -|COLUMN_NAME|`string`|Name of the column participating in the unique, primary, or foreign key. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.)| - + maps to the OLE DB KEY_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| +|TABLE_CATALOG|`string`|Catalog name in which the table containing the key column is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table containing the key column is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name containing the key column.| +|COLUMN_NAME|`string`|Name of the column participating in the unique, primary, or foreign key. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses. (DBID is a formal structure serialized into the COLUMN_NAME column of the COLUMN_DOMAIN_USAGE rowset.)| + ]]> @@ -726,17 +726,17 @@ Returns the primary key columns defined in the catalog by a given user. - maps to the OLE DB PRIMARY_KEYS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| - + maps to the OLE DB PRIMARY_KEYS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| + ]]> @@ -765,21 +765,21 @@ Returns information about the columns of rowsets returned by procedures. - maps to the OLE DB PROCEDURE_COLUMNS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|PROCEDURE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|PROCEDURE_NAME|`string`|Procedure name.| -|COLUMN_NAME|`string`|The name of the column; this might not be unique. If this cannot be determined, a null value is returned. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| - + maps to the OLE DB PROCEDURE_COLUMNS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|PROCEDURE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|PROCEDURE_NAME|`string`|Procedure name.| +|COLUMN_NAME|`string`|The name of the column; this might not be unique. If this cannot be determined, a null value is returned. This column, together with the COLUMN_GUID and COLUMN_PROPID columns, forms the column ID. One or more of these columns will be a null value, depending on which elements of the DBID structure the provider uses.| + > [!NOTE] -> The schema is not supported by any OLE DB providers that ship in MDAC version 2.7. Refer to your database documentation to determine whether you can retrieve this schema information by querying the system tables of your database. - +> The schema is not supported by any OLE DB providers that ship in MDAC version 2.7. Refer to your database documentation to determine whether you can retrieve this schema information by querying the system tables of your database. + ]]> @@ -808,18 +808,18 @@ Returns information about the parameters and return codes of procedures. - maps to the OLE DB PROCEDURE_PARAMETERS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|PROCEDURE_SCHEMA|`string`|Schema name. A null value if the provider does not support catalogs.| -|PROCEDURE_NAME|`string`|Procedure name.| -|PARAMETER_NAME|`string`|Parameter name. A null value if the parameter is not named.| - + maps to the OLE DB PROCEDURE_PARAMETERS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|PROCEDURE_SCHEMA|`string`|Schema name. A null value if the provider does not support catalogs.| +|PROCEDURE_NAME|`string`|Procedure name.| +|PARAMETER_NAME|`string`|Parameter name. A null value if the parameter is not named.| + ]]> @@ -848,18 +848,18 @@ Returns the procedures defined in the catalog that is owned by a given user. - maps to the OLE DB PROCEDURES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|PROCEDURE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|PROCEDURE_NAME|`string`|Procedure name.| -|PROCEDURE_TYPE|`UInt16`|DB_PT_UNKNOWN-It is not known whether there is a returned value.

DB_PT_PROCEDURE-Procedure; there is no returned value.

DB_PT_FUNCTION-Function; there is a returned value.| - + maps to the OLE DB PROCEDURES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|PROCEDURE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|PROCEDURE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|PROCEDURE_NAME|`string`|Procedure name.| +|PROCEDURE_TYPE|`UInt16`|DB_PT_UNKNOWN-It is not known whether there is a returned value.

DB_PT_PROCEDURE-Procedure; there is no returned value.

DB_PT_FUNCTION-Function; there is a returned value.| + ]]> @@ -888,16 +888,16 @@ Returns the base data types supported by the .NET Framework Data Provider for OLE DB. - maps to the OLE DB PROVIDER_TYPES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|DATA_TYPE|`UInt16 (Int32)`|The indicator of the data type.| -|BEST_MATCH|`Int16`|VARIANT_TRUE-The data type is the best match between all data types in the data store and the OLE DB data type indicated by the value in the DATA_TYPE column.

VARIANT_FALSE-The data type is not the best match. For each set of rows in which the value of the DATA_TYPE column is the same, the BEST_MATCH column is set to VARIANT_TRUE in only one row.| - + maps to the OLE DB PROVIDER_TYPES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|DATA_TYPE|`UInt16 (Int32)`|The indicator of the data type.| +|BEST_MATCH|`Int16`|VARIANT_TRUE-The data type is the best match between all data types in the data store and the OLE DB data type indicated by the value in the DATA_TYPE column.

VARIANT_FALSE-The data type is not the best match. For each set of rows in which the value of the DATA_TYPE column is the same, the BEST_MATCH column is set to VARIANT_TRUE in only one row.| + ]]> @@ -926,17 +926,17 @@ Returns the referential constraints defined in the catalog that is owned by a given user. - maps to the OLE DB REFERENTIAL_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| - + maps to the OLE DB REFERENTIAL_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| + ]]> @@ -964,11 +964,11 @@ Returns a list of schema rowsets, identified by their GUIDs, and a pointer to the descriptions of the restriction columns. - is equivalent to calling the OLE DB **IDBSchemaRowset::GetSchemas** interface. The list of schemas and restrictions are returned as a DataTable with two columns named "Schema" and "RestrictionSupport". Each combination of schema GUID and restriction bitmask returned by the provider will be on its on row in the DataTable. - + is equivalent to calling the OLE DB **IDBSchemaRowset::GetSchemas** interface. The list of schemas and restrictions are returned as a DataTable with two columns named "Schema" and "RestrictionSupport". Each combination of schema GUID and restriction bitmask returned by the provider will be on its on row in the DataTable. + ]]> @@ -997,17 +997,17 @@ Returns the schema objects that are owned by a given user. - maps to the OLE DB SCHEMATAS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CATALOG_NAME|`string`|Catalog name. A null value if the provider does not support catalogs.| -|SCHEMA_NAME|`string`|Unqualified schema name| -|SCHEMA_OWNER|`string`|User that owns the schemas.| - + maps to the OLE DB SCHEMATAS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CATALOG_NAME|`string`|Catalog name. A null value if the provider does not support catalogs.| +|SCHEMA_NAME|`string`|Unqualified schema name| +|SCHEMA_OWNER|`string`|User that owns the schemas.| + ]]> @@ -1036,21 +1036,21 @@ Returns the conformance levels, options, and dialects supported by the SQL-implementation processing data defined in the catalog. - maps to the OLE DB SQL_LANGUAGES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|SQL_LANGUAGE_SOURCE|`string`|"ISO 9075" for standard SQL.| -|SQL_LANGUAGE_YEAR|`string`|"1992" for ANSI SQL-92-compliant SQL.| -|SQL_LANGUAGE_CONFORMANCE|`string`|One of the following: "ENTRY", "INTERMEDIATE", or "FULL".| -|SQL_LANGUAGE_INTEGRITY|`string`|"YES"= Optional integrity feature is supported.

"NO"=Optional integrity feature is not supported.| -|SQL_LANGUAGE_IMPLEMENTATION|`string`|NULL for "ISO 9075" implementation.| -|SQL_LANGUAGE_BINDING_STYLE|`string`|"DIRECT" for C/C++ callable direct execution of SQL.| -|SQL_LANGUAGE_PROGRAMMING_LANGUAGE|`string`|NULL.| - + maps to the OLE DB SQL_LANGUAGES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|SQL_LANGUAGE_SOURCE|`string`|"ISO 9075" for standard SQL.| +|SQL_LANGUAGE_YEAR|`string`|"1992" for ANSI SQL-92-compliant SQL.| +|SQL_LANGUAGE_CONFORMANCE|`string`|One of the following: "ENTRY", "INTERMEDIATE", or "FULL".| +|SQL_LANGUAGE_INTEGRITY|`string`|"YES"= Optional integrity feature is supported.

"NO"=Optional integrity feature is not supported.| +|SQL_LANGUAGE_IMPLEMENTATION|`string`|NULL for "ISO 9075" implementation.| +|SQL_LANGUAGE_BINDING_STYLE|`string`|"DIRECT" for C/C++ callable direct execution of SQL.| +|SQL_LANGUAGE_PROGRAMMING_LANGUAGE|`string`|NULL.| + ]]> @@ -1079,17 +1079,17 @@ Returns the statistics defined in the catalog that is owned by a given user. - maps to the OLE DB STATISTICS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| - + maps to the OLE DB STATISTICS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| + ]]> @@ -1118,21 +1118,21 @@ Returns the table constraints defined in the catalog that is owned by a given user. - maps to the OLE DB TABLE_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|CONSTRAINT_NAME|`string`|Constraint name.| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|CONSTRAINT_TYPE|`string`|Constraint type. One of the following: UNIQUE, PRIMARY KEY, FOREIGN KEY, or CHECK.| - + maps to the OLE DB TABLE_CONSTRAINTS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|CONSTRAINT_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|CONSTRAINT_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|CONSTRAINT_NAME|`string`|Constraint name.| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|CONSTRAINT_TYPE|`string`|Constraint type. One of the following: UNIQUE, PRIMARY KEY, FOREIGN KEY, or CHECK.| + ]]> @@ -1161,19 +1161,19 @@ Returns the privileges on tables defined in the catalog that are available to, or granted by, a given user. - maps to the OLE DB TABLE_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|GRANTOR|`string`|User that granted the privileges on the table in TABLE_NAME.| -|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| - + maps to the OLE DB TABLE_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name in which the table is defined. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name in which the table is defined. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|GRANTOR|`string`|User that granted the privileges on the table in TABLE_NAME.| +|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| + ]]> @@ -1202,21 +1202,21 @@ Describes the available set of statistics on tables in the provider. - maps to the OLE DB TABLE_STATISTICS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name of the table of this statistic. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Schema name of the table. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| -|STATISTICS_CATALOG|`string`|Catalog name of the statistic. A null value if the provider does not support catalogs.| -|STATISTICS_SCHEMA|`string`|Schema name of the statistic. A null value if the provider does not support schemas.| -|STATISTICS_NAME|`string`|Name of the statistic.| -|STATISTICS_TYPE|`UInt16 (Int32)`|Bitmask specifying the kinds of statistics supported by this statistic:

DBSTAT_HISTOGRAM - Indicates histogram support.

DBSTAT_COLUMN_CARDINALITY - Indicates column cardinality support.

DBSTAT_TUPLE_CARDINALITY - Indicates tuple cardinality support.

`Note:` Histograms correspond to only the first column for a multi-column statistic.| - + maps to the OLE DB TABLE_STATISTICS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name of the table of this statistic. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Schema name of the table. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| +|STATISTICS_CATALOG|`string`|Catalog name of the statistic. A null value if the provider does not support catalogs.| +|STATISTICS_SCHEMA|`string`|Schema name of the statistic. A null value if the provider does not support schemas.| +|STATISTICS_NAME|`string`|Name of the statistic.| +|STATISTICS_TYPE|`UInt16 (Int32)`|Bitmask specifying the kinds of statistics supported by this statistic:

DBSTAT_HISTOGRAM - Indicates histogram support.

DBSTAT_COLUMN_CARDINALITY - Indicates column cardinality support.

DBSTAT_TUPLE_CARDINALITY - Indicates tuple cardinality support.

`Note:` Histograms correspond to only the first column for a multi-column statistic.| + ]]> @@ -1245,18 +1245,18 @@ Returns the tables (including views) defined in the catalog that are accessible to a given user. - maps to the OLE DB TABLES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name. The column returned cannot contain a null value.| -|TABLE_TYPE|`string`|Table type. One of the following or a provider-specific value: "ALIAS", "TABLE" "SYNONYM", "SYSTEM TABLE", "VIEW", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", or "SYSTEM VIEW". The column returned cannot contain a null value.| - + maps to the OLE DB TABLES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name. The column returned cannot contain a null value.| +|TABLE_TYPE|`string`|Table type. One of the following or a provider-specific value: "ALIAS", "TABLE" "SYNONYM", "SYSTEM TABLE", "VIEW", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", or "SYSTEM VIEW". The column returned cannot contain a null value.| + ]]> @@ -1285,18 +1285,18 @@ Returns the tables (including views) that are accessible to a given user. - maps to the OLE DB TABLES_INFO rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_TYPE|`string`|Table type. One of the following or a provider-specific value: ALIAS, TABLE, SYNONYM, SYSTEM TABLE, VIEW, GLOBAL TEMPORARY, LOCAL TEMPORARY, EXTERNAL TABLE, or SYSTEM VIEW.| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|Table name.| - + maps to the OLE DB TABLES_INFO rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_TYPE|`string`|Table type. One of the following or a provider-specific value: ALIAS, TABLE, SYNONYM, SYSTEM TABLE, VIEW, GLOBAL TEMPORARY, LOCAL TEMPORARY, EXTERNAL TABLE, or SYSTEM VIEW.| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|Table name.| + ]]> @@ -1325,17 +1325,17 @@ Returns the character translations defined in the catalog that is accessible to a given user. - maps to the OLE DB TRANSLATIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TRANSLATION_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TRANSLATION_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TRANSLATION_NAME|`string`|Translation name.| - + maps to the OLE DB TRANSLATIONS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TRANSLATION_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TRANSLATION_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TRANSLATION_NAME|`string`|Translation name.| + ]]> @@ -1364,18 +1364,18 @@ Identifies the trustees defined in the data source. - maps to the OLE DB TRUSTEE schema. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TRUSTEE_NAME|`string`|Trustee name.| -|TRUSTEE_GUID|`guid`|GUID that uniquely identifies the trustee. Providers that do no use GUIDs to identify trustees should return a null value in this column.| -|TRUSTEE_PROPID|`UInt32 (Int64)`|PropID that uniquely identifies the trustee. Providers that do not use PropIDs to identify trustees should return a null value in this column.| -|TRUSTEE_TYPE|`UInt32 (Int64)`|Trustee type. One of the following:

TRUSTEE_IS_UNKNOWN - The trustee is an unknown type, but not necessarily an invalid type.

TRUSTEE_IS_USER - The trustee account is a user account.

TRUSTEE_IS_GROUP - The trustee is a group account.| - + maps to the OLE DB TRUSTEE schema. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TRUSTEE_NAME|`string`|Trustee name.| +|TRUSTEE_GUID|`guid`|GUID that uniquely identifies the trustee. Providers that do no use GUIDs to identify trustees should return a null value in this column.| +|TRUSTEE_PROPID|`UInt32 (Int64)`|PropID that uniquely identifies the trustee. Providers that do not use PropIDs to identify trustees should return a null value in this column.| +|TRUSTEE_TYPE|`UInt32 (Int64)`|Trustee type. One of the following:

TRUSTEE_IS_UNKNOWN - The trustee is an unknown type, but not necessarily an invalid type.

TRUSTEE_IS_USER - The trustee account is a user account.

TRUSTEE_IS_GROUP - The trustee is a group account.| + ]]> @@ -1404,20 +1404,20 @@ Returns the USAGE privileges on objects defined in the catalog that are available to or granted by a given user. - maps to the OLE DB USAGE_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|OBJECT_CATALOG|`string`|Catalog name in which the object is defined. A null value if the provider does not support catalogs.| -|OBJECT_SCHEMA|`string`|Unqualified schema name in which the object is defined. A null value if the provider does not support schemas.| -|OBJECT_NAME|`string`|Object name.| -|OBJECT_TYPE|`string`|Object type. One of the following: DOMAIN, CHARACTER SET, COLLATION, or TRANSLATION.| -|GRANTOR|`string`|User that granted the privileges on the object in OBJECT_NAME.| -|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| - + maps to the OLE DB USAGE_PRIVILEGES rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|OBJECT_CATALOG|`string`|Catalog name in which the object is defined. A null value if the provider does not support catalogs.| +|OBJECT_SCHEMA|`string`|Unqualified schema name in which the object is defined. A null value if the provider does not support schemas.| +|OBJECT_NAME|`string`|Object name.| +|OBJECT_TYPE|`string`|Object type. One of the following: DOMAIN, CHARACTER SET, COLLATION, or TRANSLATION.| +|GRANTOR|`string`|User that granted the privileges on the object in OBJECT_NAME.| +|GRANTEE|`string`|User name (or "PUBLIC") that the privilege has been granted to.| + ]]> @@ -1446,17 +1446,17 @@ Returns the columns on which viewed tables depend, as defined in the catalog and owned by a given user. - maps to the OLE DB VIEW_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|VIEW_CATALOG|string|Catalog name. A null value if the provider does not support catalogs.| -|VIEW_SCHEMA|string|Unqualified schema name. A null value if the provider does not support schemas.| -|VIEW_NAME|string|View name.| - + maps to the OLE DB VIEW_COLUMN_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|VIEW_CATALOG|string|Catalog name. A null value if the provider does not support catalogs.| +|VIEW_SCHEMA|string|Unqualified schema name. A null value if the provider does not support schemas.| +|VIEW_NAME|string|View name.| + ]]> @@ -1485,17 +1485,17 @@ Returns the tables on which viewed tables, defined in the catalog and owned by a given user, are dependent. - maps to the OLE DB VIEW_TABLE_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|VIEW_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|VIEW_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|VIEW_NAME|`string`|View name.| - + maps to the OLE DB VIEW_TABLE_USAGE rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|VIEW_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|VIEW_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|VIEW_NAME|`string`|View name.| + ]]> @@ -1524,17 +1524,17 @@ Returns the views defined in the catalog that is accessible to a given user. - maps to the OLE DB VIEWS rowset. Unless otherwise specified, restriction columns are returned in the following order. - -|Restriction column|CLR data type|Description| -|------------------------|-------------------|-----------------| -|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| -|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| -|TABLE_NAME|`string`|View name.| - + maps to the OLE DB VIEWS rowset. Unless otherwise specified, restriction columns are returned in the following order. + +|Restriction column|CLR data type|Description| +|------------------------|-------------------|-----------------| +|TABLE_CATALOG|`string`|Catalog name. A null value if the provider does not support catalogs.| +|TABLE_SCHEMA|`string`|Unqualified schema name. A null value if the provider does not support schemas.| +|TABLE_NAME|`string`|View name.| + ]]> diff --git a/xml/System.Data.OleDb/OleDbTransaction.xml b/xml/System.Data.OleDb/OleDbTransaction.xml index 81214fe2aa3..79405ce0e06 100644 --- a/xml/System.Data.OleDb/OleDbTransaction.xml +++ b/xml/System.Data.OleDb/OleDbTransaction.xml @@ -58,11 +58,11 @@ Represents an SQL transaction to be made at a data source. This class cannot be inherited. - object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. - + object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. + ]]> @@ -106,11 +106,11 @@ Initiates a nested database transaction. A nested database transaction. - Nested transactions are not supported. @@ -146,11 +146,11 @@ Initiates a nested database transaction and specifies the isolation level to use for the new transaction. A nested database transaction. - Nested transactions are not supported. @@ -190,21 +190,21 @@ Commits the database transaction. - and an . It also demonstrates how to use the , a , and methods. - + and an . It also demonstrates how to use the , a , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source1.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing Transactions @@ -235,11 +235,11 @@ Gets the object associated with the transaction, or if the transaction is no longer valid. The object associated with the transaction. - . - + . + ]]> Performing Transactions @@ -358,11 +358,11 @@ Specifies the for this transaction. The for this transaction. The default is . - applies to the whole transaction. - + applies to the whole transaction. + ]]> Performing Transactions @@ -401,26 +401,26 @@ Rolls back a transaction from a pending state. - has been called, but before is called). The transaction will be rolled back in the event it is disposed before `Commit` or `Rollback` is called. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , a , and methods. - + has been called, but before is called). The transaction will be rolled back in the event it is disposed before `Commit` or `Rollback` is called. + + + +## Examples + The following example creates an and an . It also demonstrates how to use the , a , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnection/BeginTransaction/source1.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing Transactions diff --git a/xml/System.Data.OracleClient/OracleBFile.xml b/xml/System.Data.OracleClient/OracleBFile.xml index a11430bbf21..e59b2e2f93c 100644 --- a/xml/System.Data.OracleClient/OracleBFile.xml +++ b/xml/System.Data.OracleClient/OracleBFile.xml @@ -50,15 +50,15 @@ - The file name of the underlying physical file, which is located in the directory associated with the DIRECTORY object. - After a `BFILE` is created, you can retrieve its locator in the form of an object using the or methods. + After a `BFILE` is created, you can retrieve its locator in the form of an object using the or methods. - To obtain an object, call the method. + To obtain an object, call the method. - The physical file that an object is associated with does not need to exist until you attempt to access it. An application can bind an to a nonexistent file, create the physical file in the expected location, and then call . + The physical file that an object is associated with does not need to exist until you attempt to access it. An application can bind an to a nonexistent file, create the physical file in the expected location, and then call . - Any attempt to access a closed using the or methods reopens an stream automatically. + Any attempt to access a closed using the or methods reopens an stream automatically. - The following C# example demonstrates how you can create a `BFILE` in an Oracle table, and then retrieve it in the form of an object. The example demonstrates the use of the object and the and methods. + The following C# example demonstrates how you can create a `BFILE` in an Oracle table, and then retrieve it in the form of an object. The example demonstrates the use of the object and the and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OracleClient.BFile/CS/source.cs" id="Snippet1"::: @@ -170,7 +170,7 @@ object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. + The properties of the new object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. ]]> @@ -239,7 +239,7 @@ ## Remarks The underlying data types of the source and the destination must be compatible. For example, you cannot copy binary data to a destination that has a character data type. - You must have write access to the destination for the operation to execute correctly. + You must have write access to the destination for the operation to execute correctly. ]]> @@ -285,7 +285,7 @@ ## Remarks The underlying data types of the source and the destination must be compatible. For example, you cannot copy binary data to a destination that has a character data type. - You must have write access to the destination for the operation to execute correctly. + You must have write access to the destination for the operation to execute correctly. ]]> @@ -335,7 +335,7 @@ ## Remarks The underlying data types of the source and the destination must be compatible. For example, you cannot copy binary data to a destination that has a character data type. - You must have write access to the destination for the operation to execute correctly. + You must have write access to the destination for the operation to execute correctly. ]]> @@ -663,9 +663,9 @@ method read a maximum of `count` bytes from the current stream and store them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. returns the number of bytes read. The return value is zero only if the position is currently at the end of the stream. will block until at least one byte of data can be read, in the event that no data is available. returns 0 only when the end of the file has been reached. is free to return fewer bytes than requested even if the end of the stream has not been reached. + The method read a maximum of `count` bytes from the current stream and store them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. returns the number of bytes read. The return value is zero only if the position is currently at the end of the stream. will block until at least one byte of data can be read, in the event that no data is available. returns 0 only when the end of the file has been reached. is free to return fewer bytes than requested even if the end of the stream has not been reached. - Any attempt to access a closed using the or methods reopens an stream automatically. + Any attempt to access a closed using the or methods reopens an stream automatically. The following C# example assumes this schema in an Oracle table: @@ -673,7 +673,7 @@ (col1 number, col2 BFILE) ``` - The example demonstrates using the and methods to access an object. + The example demonstrates using the and methods to access an object. ```csharp byte[] buffer = new byte[100]; @@ -735,7 +735,7 @@ using (dataReader) { Seeking to any location beyond the length of the stream is not supported. - Any attempt to access a closed using the or methods reopens an stream automatically. + Any attempt to access a closed using the or methods reopens an stream automatically. The following C# example assumes this schema in an Oracle table: @@ -743,7 +743,7 @@ using (dataReader) { (col1 number, col2 BFILE) ``` - The example demonstrates using the and methods to access an object. + The example demonstrates using the and methods to access an object. ```csharp byte[] buffer = new byte[100]; @@ -794,11 +794,11 @@ using (dataReader) { operation must be within a transaction to succeed. Simply calling on a `BFILE` associates the object with a different file, but does not update the Oracle table. To update the Oracle table after calling , you must call the `Update` method of the and then commit the transaction. + The operation must be within a transaction to succeed. Simply calling on a `BFILE` associates the object with a different file, but does not update the Oracle table. To update the Oracle table after calling , you must call the `Update` method of the and then commit the transaction. - Once you retrieve the or property, they are cached in the object and are unaffected by any cloned objects' calls to , or by any changes to the `BFILE` in the database. In other words, they might not represent the actual values of the `BFILE` object in the server. + Once you retrieve the or property, they are cached in the object and are unaffected by any cloned objects' calls to , or by any changes to the `BFILE` in the database. In other words, they might not represent the actual values of the `BFILE` object in the server. - Furthermore, retrieving either property ( or ) causes both property values to be retrieved from the server and cached in the object. + Furthermore, retrieving either property ( or ) causes both property values to be retrieved from the server and cached in the object. The following C# example assumes this schema in an Oracle table: @@ -806,7 +806,7 @@ using (dataReader) { (col1 number, col2 BFILE) ``` - The example demonstrates using the , and methods to access an object. + The example demonstrates using the , and methods to access an object. ```csharp byte[] buffer = new byte[100]; @@ -884,7 +884,7 @@ using (dataReader) { The property reads the entire `BFILE` at one time. > [!NOTE] -> A benefit of using `BFILE`s is the ability to retrieve large amounts of data in chunks at the client. However, when you use , you obtain all the data for the BFILE column as one contiguous chunk, which can significantly increase application overhead. +> A benefit of using `BFILE`s is the ability to retrieve large amounts of data in chunks at the client. However, when you use , you obtain all the data for the BFILE column as one contiguous chunk, which can significantly increase application overhead. ]]> diff --git a/xml/System.Data.OracleClient/OracleBinary.xml b/xml/System.Data.OracleClient/OracleBinary.xml index b03558701d8..e6775cb5a07 100644 --- a/xml/System.Data.OracleClient/OracleBinary.xml +++ b/xml/System.Data.OracleClient/OracleBinary.xml @@ -28,7 +28,7 @@ object, call the method. + To obtain an object, call the method. ]]> @@ -526,7 +526,7 @@ In Visual Basic, you can use the operators defined by a class, but you cannot override them or create your own. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -557,7 +557,7 @@ Compares two structures to determine if they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -624,7 +624,7 @@ Compares two structures to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -655,7 +655,7 @@ Compares two structures to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -713,7 +713,7 @@ Compares two structures to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -744,7 +744,7 @@ Compares two structures to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -775,7 +775,7 @@ Compares two structures to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleBoolean.xml b/xml/System.Data.OracleClient/OracleBoolean.xml index 8d95d5e959c..1ea9c536c25 100644 --- a/xml/System.Data.OracleClient/OracleBoolean.xml +++ b/xml/System.Data.OracleClient/OracleBoolean.xml @@ -331,7 +331,7 @@ is , this property still is `false`. + If the is , this property still is `false`. ]]> @@ -391,7 +391,7 @@ is , this property still is `false`. + If the is , this property still is `false`. ]]> @@ -548,7 +548,7 @@ - ]]> + ]]> @@ -583,7 +583,7 @@ - ]]> + ]]> @@ -614,7 +614,7 @@ Compares two instances of an for equality. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -649,7 +649,7 @@ - ]]> + ]]> @@ -835,7 +835,7 @@ Compares two instances of for inequality. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -891,7 +891,7 @@ Performs a one's complement operation on the specified . The one's complement of the specified . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleCommand.xml b/xml/System.Data.OracleClient/OracleCommand.xml index 81038049799..a60ed27df5b 100644 --- a/xml/System.Data.OracleClient/OracleCommand.xml +++ b/xml/System.Data.OracleClient/OracleCommand.xml @@ -69,11 +69,11 @@ |Item|Description| |----------|-----------------| -||Executes commands that return rows.| -||Executes an SQL statement against the and returns the number of rows affected.| -||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| -||Retrieves a single value (for example, an aggregate value) from a database as a .NET Framework data type.| -||Retrieves a single value (for example, an aggregate value) from a database as an Oracle-specific data type.| +||Executes commands that return rows.| +||Executes an SQL statement against the and returns the number of rows affected.| +||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| +||Retrieves a single value (for example, an aggregate value) from a database as a .NET Framework data type.| +||Retrieves a single value (for example, an aggregate value) from a database as an Oracle-specific data type.| You can reset the property and reuse the object. @@ -121,9 +121,9 @@ | Properties | Initial Value | |--------------------------------------------------------------|-------------------| -| | empty string ("") | -| | `Text` | -| | null | +| | empty string ("") | +| | `Text` | +| | null | ]]> @@ -212,9 +212,9 @@ | Properties | Initial Value | |--------------------------------------------------------------|---------------| -| | `cmdText` | -| | `Text` | -| | A new that is the value for the `connection` parameter. | +| | `cmdText` | +| | `Text` | +| | A new that is the value for the `connection` parameter. | You can change the value for any of these parameters by setting the related property. @@ -437,9 +437,9 @@ property is set to `StoredProcedure`, you should set the property to the full Oracle call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). + When the property is set to `StoredProcedure`, you should set the property to the full Oracle call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). - The , and properties cannot be set if the current connection is performing an execute or fetch operation. + The , and properties cannot be set if the current connection is performing an execute or fetch operation. The .NET Framework Data Provider for Oracle does not support the question mark (?) placeholder for passing parameters to an SQL statement called by an of `CommandType.Text`. In this case, named parameters must be used. @@ -493,9 +493,9 @@ , , and properties if the current connection is performing an execute or fetch operation. + You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. + If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. ]]> @@ -552,7 +552,7 @@ method is a strongly-typed version of . + The method is a strongly-typed version of . ]]> @@ -730,9 +730,9 @@ to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. + You can use to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. - Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. + Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For CREATE TABLE and DROP TABLE statements, the return value is 0. For all other types of statements, the return value is -1. If a rollback occurs, the return value is also -1. @@ -774,11 +774,11 @@ to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. + You can use to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables); or to change the data in a database, without using a , by executing UPDATE, INSERT, or DELETE statements. - differs from in that it returns `rowid` as an output parameter if you are executing an INSERT, DELETE, or UPDATE statement that affects exactly one row. This allows you to uniquely identify a row in the Oracle database, which can allow you to increase performance in subsequent, related queries. + differs from in that it returns `rowid` as an output parameter if you are executing an INSERT, DELETE, or UPDATE statement that affects exactly one row. This allows you to uniquely identify a row in the Oracle database, which can allow you to increase performance in subsequent, related queries. - Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. + Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. ]]> @@ -815,7 +815,7 @@ method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value from the data returned by an . + Use the method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value from the data returned by an . ]]> @@ -858,7 +858,7 @@ property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . More than one can be open at any given time. @@ -898,7 +898,7 @@ ## Remarks If you expect your SQL statement to return only a single row, specifying `SingleRow` as the value may improve application performance. - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . @@ -942,7 +942,7 @@ method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value from the data returned by an . + Use the method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value from the data returned by an . ]]> @@ -1022,7 +1022,7 @@ , specify the data type of each parameter in the statement to be prepared. + Before you call , specify the data type of each parameter in the statement to be prepared. ]]> @@ -1057,7 +1057,7 @@ is 30 seconds. + The default value of the is 30 seconds. ]]> @@ -1150,7 +1150,7 @@ For more information, see . . +For more information, see . ]]> diff --git a/xml/System.Data.OracleClient/OracleCommandBuilder.xml b/xml/System.Data.OracleClient/OracleCommandBuilder.xml index 04b7cd25dd9..1ce986c69cb 100644 --- a/xml/System.Data.OracleClient/OracleCommandBuilder.xml +++ b/xml/System.Data.OracleClient/OracleCommandBuilder.xml @@ -41,9 +41,9 @@ To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. - The also uses the , and properties referenced by the . + The also uses the , and properties referenced by the . - If you call , the is disassociated from the , and the generated commands are no longer used. + If you call , the is disassociated from the , and the generated commands are no longer used. ]]> @@ -287,11 +287,11 @@ overwrites any existing parameter information for the . + overwrites any existing parameter information for the . - requires an extra call to the database to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. + requires an extra call to the database to obtain the information. If the parameter information is known in advance, it is more efficient to populate the parameters collection by setting the information explicitly. - You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. + You can only use with stored procedures. You cannot use to populate the with arbitrary Transact-SQL statements, such as a parameterized SELECT statement. For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). @@ -335,11 +335,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -373,11 +373,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -413,11 +413,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on, for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -444,11 +444,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -482,11 +482,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -522,11 +522,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on, for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -631,11 +631,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -669,11 +669,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -709,11 +709,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + You can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - The SQL statements are first generated when the application calls either or . + The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on, for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter allows you to force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: diff --git a/xml/System.Data.OracleClient/OracleConnection.xml b/xml/System.Data.OracleClient/OracleConnection.xml index 16a7dcce7b2..450a7ee8701 100644 --- a/xml/System.Data.OracleClient/OracleConnection.xml +++ b/xml/System.Data.OracleClient/OracleConnection.xml @@ -54,9 +54,9 @@ An application that creates an instance of the object can set declarative or imperative security demands that require all direct and indirect callers to have adequate permission to the code. creates security demands by using the object. Users can verify that their code has adequate permissions by using the object. Users and administrators can also use the Code Access Security Policy Tool (Caspol.exe) to modify security policy at the machine, user, and enterprise levels. For more information, see [Security](/dotnet/standard/security/). > [!NOTE] -> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. - If the object goes out of scope, it remains open. Therefore, you should always close objects by calling or **Dispose**, or by using the object within a `Using` statement. Otherwise, the garbage collection might not free them immediately. Such delays can cause errors if the maximum number of connections is reached while a number of connections are waiting to be deleted by the garbage collector. By contrast, closing the connections by calling uses native resources more efficiently, enhancing scalability and improving overall application performance. To ensure that connections are always closed, open the connection inside of a `Using` block. + If the object goes out of scope, it remains open. Therefore, you should always close objects by calling or **Dispose**, or by using the object within a `Using` statement. Otherwise, the garbage collection might not free them immediately. Such delays can cause errors if the maximum number of connections is reached while a number of connections are waiting to be deleted by the garbage collector. By contrast, closing the connections by calling uses native resources more efficiently, enhancing scalability and improving overall application performance. To ensure that connections are always closed, open the connection inside of a `Using` block. > [!NOTE] > To deploy high-performance applications, you often need to use connection pooling. However, when you use the .NET Framework Data Provider for Oracle, you do not need to enable connection pooling because the provider manages this automatically. @@ -179,12 +179,12 @@ or methods. + To commit or roll back the transaction, you must explicitly use the or methods. To ensure that the .NET Framework Data Provider for Oracle transaction management model performs correctly, avoid using other transaction management models, such as those provided by the database. > [!NOTE] -> If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the method, use the overload. +> If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the method, use the overload. ]]> @@ -222,7 +222,7 @@ or methods. + To commit or roll back the transaction, you must explicitly use the or methods. To ensure that the .NET Framework Data Provider for Oracle transaction management model performs correctly, avoid using other transaction management models, such as those provided by the database. @@ -262,7 +262,7 @@ The `value` parameter must contain a valid database name, and cannot contain a null value, an empty string (""), or a string with only blank characters. > [!NOTE] -> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -294,7 +294,7 @@ resets (or empties) the connection pool. If connections are in use at the time of the call, they are marked appropriately and are discarded when is called on them. + resets (or empties) the connection pool. If connections are in use at the time of the call, they are marked appropriately and are discarded when is called on them. ]]> @@ -326,7 +326,7 @@ method clears the connection pool that is associated with `connection`. If additional connections associated with `connection` are in use at the time of the call, they are marked appropriately and are discarded when is called on them. + method clears the connection pool that is associated with `connection`. If additional connections associated with `connection` are in use at the time of the call, they are marked appropriately and are discarded when is called on them. ]]> @@ -364,15 +364,15 @@ method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. + The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. - An application can call more than once without generating an exception. + An application can call more than once without generating an exception. > [!NOTE] > When you use the .NET Framework Data Provider for Oracle, you do not need to enable connection pooling because the provider manages this automatically. > [!CAUTION] -> Do not call on a , a , or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). +> Do not call on a , a , or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). ]]> @@ -438,13 +438,13 @@ can be set only when the connection is closed. + The can be set only when the connection is closed. You can use the property to connect to a database. - Many of the settings specified in the string have corresponding read-only properties (for example, `Data Source=MyServer`, which corresponds to the property). When the connection string is set, all of these properties are updated, unless an error is detected, in which case none of the properties are updated. properties return only default settings or those settings specified in the . + Many of the settings specified in the string have corresponding read-only properties (for example, `Data Source=MyServer`, which corresponds to the property). When the connection string is set, all of these properties are updated, unless an error is detected, in which case none of the properties are updated. properties return only default settings or those settings specified in the . - Resetting the on a closed connection resets all connection string values (and related properties), including the password. + Resetting the on a closed connection resets all connection string values (and related properties), including the password. The connection string is parsed immediately after being set. If parsing reveals errors in syntax, a run-time exception, such as , is generated. Other errors can be found only when an attempt is made to open the connection. @@ -464,24 +464,24 @@ Keywords are case insensitive. - The following table lists the valid names for values within the . + The following table lists the valid names for values within the . |Name|Default|Description| |----------|-------------|-----------------| |Data Source

-or-

Server||The name or network address of the instance of Oracle to which to connect.| |Integrated Security|'false'|Whether the connection is to be a secure connection or not.

Recognized values are `true` (strongly recommended), `false`, `yes`, and `no`.| |Password||The password for the Oracle account logging on. To maintain a high level of security, we strongly recommend that you use the Integrated Security keyword instead.| -|Persist Security Info|'false'|When set to `false` or `no` (strongly recommended), security-sensitive information such as the password is not returned as part of the connection if the connection is open or has ever been in an open . Resetting the connection string resets all connection string values, including the password.

Recognized values are `true`, `false`, `yes`, and `no`.| +|Persist Security Info|'false'|When set to `false` or `no` (strongly recommended), security-sensitive information such as the password is not returned as part of the connection if the connection is open or has ever been in an open . Resetting the connection string resets all connection string values, including the password.

Recognized values are `true`, `false`, `yes`, and `no`.| |Unicode|'false'|Specifies whether the .NET Framework Data Provider for Oracle uses UTF16 mode API calls. This keyword is ignored except when using Oracle9i client software.| |User ID||The Oracle login account. To maintain a high level of security, we strongly recommend that you use the Integrated Security keyword instead.| - The following table lists the valid names for connection pooling values within the . + The following table lists the valid names for connection pooling values within the . |Name|Default|Description| |----------|-------------|-----------------| |Connection Lifetime|0|When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime`. This is useful in clustered configurations to force load balancing between a running server and a server just brought online.

A value of zero causes pooled connections to have the maximum connection time-out.| |Enlist|'true'|When `true` or `yes`, the pooler automatically enlists the connection in the creation thread's current transaction context.

Recognized values are `true`, `false`, `yes`, and `no`.| -|Max Pool Size|100|The maximum number of connections allowed in the pool. Setting the `Max Pool Size` value of the can affect performance. If you plan to create and actively use more than 100 connections, you should increase `Max Pool Size` to a value that approximates the steady-state connection usage for the application.| +|Max Pool Size|100|The maximum number of connections allowed in the pool. Setting the `Max Pool Size` value of the can affect performance. If you plan to create and actively use more than 100 connections, you should increase `Max Pool Size` to a value that approximates the steady-state connection usage for the application.| |Min Pool Size|0|The minimum number of connections allowed in the pool.| |Pooling|'true'|When `true` or `yes`, the object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool.

Recognized values are `true`, `false`, `yes`, and `no`.| @@ -524,10 +524,10 @@ because an attempt to connect waits indefinitely. + You can set the amount of time a connection waits to time out by using the `Connect Timeout` or `Connection Timeout` keywords in the connection string. A value of 0 indicates no limit, and should be avoided in a because an attempt to connect waits indefinitely. > [!NOTE] -> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -615,10 +615,10 @@ property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. > [!NOTE] -> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -715,13 +715,13 @@ method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + New in ADO.NET 2.0 is support for using the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). You can continue to enlist in an existing distributed transaction using the - method if auto-enlistment is disabled. Enlisting in an existing distributed transaction ensures that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. + method if auto-enlistment is disabled. Enlisting in an existing distributed transaction ensures that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. - returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . + returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), rolls back the local transaction and enlists in the existing distributed transaction as requested. You will not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . ]]> @@ -755,7 +755,7 @@ ## Remarks New in ADO.NET 2.0 is support for using the - method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). ]]> @@ -822,7 +822,7 @@ are case sensitive. Because of Oracle's treatment of cases when a schema is first created, this can lead to unexpected results. + Queries using are case sensitive. Because of Oracle's treatment of cases when a schema is first created, this can lead to unexpected results. If the schema was created without quotes`,` Oracle stores the object name in upper case. If the schema was created with quotes, Oracle stores the object name in the casing provided. @@ -874,7 +874,7 @@ An example of this is the "Tables" collection. If the "Tables" collection has 3 restrictions: database, owner, and table name; and you want to get back only the tables associated with the owner "Carl", then you would need to pass in the following values (at a minimum): null, "Carl". If a restriction value is not passed in, the default values are used for that restriction. This is the same mapping as passing in null, which is different than passing in an empty string for the parameter value. In that case, the empty string ("") is considered to be the value for the specified parameter. - Queries using are case sensitive. Because of Oracle's treatment of cases when a schema is first created, this can lead to unexpected results. + Queries using are case sensitive. Because of Oracle's treatment of cases when a schema is first created, this can lead to unexpected results. If the schema was created without quotes`,` Oracle stores the object name in upper case. If the schema was created with quotes, Oracle stores the object name in the casing provided. @@ -916,7 +916,7 @@ event is generated. An example would be creating a stored procedure that contains a syntax error. The call to the method would succeed. However an event would be generated informing you of the syntax error. + Because the .NET Framework Data Provider for Oracle uses the Oracle Call Interface (OCI), whenever the data provider receives a Success With Info message, an event is generated. An example would be creating a stored procedure that contains a syntax error. The call to the method would succeed. However an event would be generated informing you of the syntax error. Clients who want to process warnings or informational messages sent by the server should create an delegate to listen to this event. @@ -959,7 +959,7 @@ The draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to the database. > [!NOTE] -> If the goes out of scope, the connection it represents does not close automatically. Therefore, you must explicitly close the connection by calling . +> If the goes out of scope, the connection it represents does not close automatically. Therefore, you must explicitly close the connection by calling . ]]> @@ -1054,7 +1054,7 @@ The allowed state changes are: - From `Closed` to `Open`, using the `Open` method of the object. -- From `Open` to `Closed`, using the method of the object. +- From `Open` to `Closed`, using the method of the object. ]]> diff --git a/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml b/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml index 0f8a4f40d3f..54315372c94 100644 --- a/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml +++ b/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml @@ -131,7 +131,7 @@ method removes all key/value pairs from the , and resets all corresponding properties. This includes resetting the connection string to an empty string. + The method removes all key/value pairs from the , and resets all corresponding properties. This includes resetting the connection string to an empty string. ]]> @@ -166,7 +166,7 @@ contains a fixed-size collection of key/value pairs, the method determines only if a particular key name is valid. + Because the contains a fixed-size collection of key/value pairs, the method determines only if a particular key name is valid. ]]> @@ -372,18 +372,18 @@ |Key|Property|Default value| |---------|--------------|-------------------| -|Data Source (or server)||Empty string| -|Persist Security Info (or persistsecurityinfo)||False| -|Integrated Security||False| -|User ID (or user or uid)||Empty string| -|Password||Empty string| -|Enlist||True| -|Pooling||True| -|Min Pool Size||0| -|Max Pool Size||100| -|Omit Oracle Connection Name||False| -|Unicode||False| -|Load Balance Timeout (or connection lifetime)||0| +|Data Source (or server)||Empty string| +|Persist Security Info (or persistsecurityinfo)||False| +|Integrated Security||False| +|User ID (or user or uid)||Empty string| +|Password||Empty string| +|Enlist||True| +|Pooling||True| +|Min Pool Size||0| +|Max Pool Size||100| +|Omit Oracle Connection Name||False| +|Unicode||False| +|Load Balance Timeout (or connection lifetime)||0| ]]> @@ -743,11 +743,11 @@ method returns a value that indicates its success, so it's not necessary to look for the existence of a key before trying to remove the key/value pair from the instance. Calling the method just resets the value of the key/value pair back to its default value. That's because the maintains a fixed-size collection of key/value pairs +The method returns a value that indicates its success, so it's not necessary to look for the existence of a key before trying to remove the key/value pair from the instance. Calling the method just resets the value of the key/value pair back to its default value. That's because the maintains a fixed-size collection of key/value pairs The collection of keys supported by the is fixed, so every item within the collection has a known default value. - The following table lists the keys, and the value for each when the is first initialized, or after the method has been called. + The following table lists the keys, and the value for each when the is first initialized, or after the method has been called. | Key | Default value | |-----------------------------|---------------| @@ -799,7 +799,7 @@ The collection of keys supported by the method. + This method behaves identically to the method. ]]> @@ -836,7 +836,7 @@ The collection of keys supported by the method lets developers safely retrieve a value from an without needing to verify that the supplied key name is a valid key name. Because gracefully handles searching for a non-existent key, there is no need to look for the existence of a key before retrieving its value. Calling with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from an without needing to verify that the supplied key name is a valid key name. Because gracefully handles searching for a non-existent key, there is no need to look for the existence of a key before retrieving its value. Calling with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. ]]> diff --git a/xml/System.Data.OracleClient/OracleDataAdapter.xml b/xml/System.Data.OracleClient/OracleDataAdapter.xml index 406c134b36a..1c49c02f076 100644 --- a/xml/System.Data.OracleClient/OracleDataAdapter.xml +++ b/xml/System.Data.OracleClient/OracleDataAdapter.xml @@ -72,16 +72,16 @@ ## Remarks This type is deprecated and will be removed in a future version of the .NET Framework. For more information, see [Oracle and ADO.NET](/dotnet/framework/data/adonet/oracle-and-adonet). - The serves as a bridge between a **DataSet** and database for retrieving and saving data. The provides this bridge by using to load data from the database into the , and using to send changes made in the back to the data source. + The serves as a bridge between a **DataSet** and database for retrieving and saving data. The provides this bridge by using to load data from the database into the , and using to send changes made in the back to the data source. - When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). > [!NOTE] -> By default, numeric fields imported to a with are mapped to objects. It is possible to overflow the , and throw an Oracle exception, by importing a non-integral numeric value that is either too large or too high precision for the 's precision limitations. Refer to the description of for more information. +> By default, numeric fields imported to a with are mapped to objects. It is possible to overflow the , and throw an Oracle exception, by importing a non-integral numeric value that is either too large or too high precision for the 's precision limitations. Refer to the description of for more information. - The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. + The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. - The .NET Framework Data Provider for Oracle does not support batched SQL statements. However, it does allow you to use multiple `REF CURSOR` output parameters to fill a **DataSet**, each in its own . You must define the parameters, mark them as output parameters, and indicate that they are `REF CURSOR` data types. Note that you cannot use the method when the is filled using `REF CURSOR` parameters returned by a stored procedure, because Oracle does not provide the information necessary to determine what the table name and column names are when the SQL statement is executed. + The .NET Framework Data Provider for Oracle does not support batched SQL statements. However, it does allow you to use multiple `REF CURSOR` output parameters to fill a **DataSet**, each in its own . You must define the parameters, mark them as output parameters, and indicate that they are `REF CURSOR` data types. Note that you cannot use the method when the is filled using `REF CURSOR` parameters returned by a stored procedure, because Oracle does not provide the information necessary to determine what the table name and column names are when the SQL statement is executed. After using the to perform a `Fill` or `FillSchema` operation, the `DataColumn.ReadOnly` property always returns false, regardless of whether a column can be updated or not, because the Oracle server does not return this information. @@ -123,8 +123,8 @@ | Properties | Default value | |---------------------------------------------------------------|------------------------------------| -| | `MissingMappingAction.Passthrough` | -| | `MissingSchemaAction.Add` | +| | `MissingMappingAction.Passthrough` | +| | `MissingSchemaAction.Add` | You can change the value of any of these properties through a separate call to the property. @@ -163,8 +163,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -388,9 +388,9 @@ property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . + When the property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). ]]> @@ -542,9 +542,9 @@ property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . + When the property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] > If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. @@ -736,9 +736,9 @@ is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - If does not return any rows, no tables are added to the **DataSet**, and no exception is raised. + If does not return any rows, no tables are added to the **DataSet**, and no exception is raised. ]]> @@ -1024,9 +1024,9 @@ is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - During an update operation, if is not set and primary key information is present in the **DataSet**, you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the **DataSet**, you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] > If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. diff --git a/xml/System.Data.OracleClient/OracleDataReader.xml b/xml/System.Data.OracleClient/OracleDataReader.xml index b78772d8330..2580b164d98 100644 --- a/xml/System.Data.OracleClient/OracleDataReader.xml +++ b/xml/System.Data.OracleClient/OracleDataReader.xml @@ -40,11 +40,11 @@ , you must call the method of the object, rather than directly using a constructor. + To create an , you must call the method of the object, rather than directly using a constructor. Changes made to a resultset by another process or thread while data is being read may be visible to the user of the . - and are the only properties that you can call after the is closed. In some cases, you must call before you can call . + and are the only properties that you can call after the is closed. In some cases, you must call before you can call . More than one can be open at any given time. @@ -380,9 +380,9 @@ public void ReadOracleTypesExample(string connectionString) to exclude hidden fields. + Includes hidden fields. Use to exclude hidden fields. - After executing a query that does not return rows, returns 0. + After executing a query that does not return rows, returns 0. ]]> @@ -425,7 +425,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -468,7 +468,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -519,9 +519,9 @@ public void ReadOracleTypesExample(string connectionString) returns the number of available bytes in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . + returns the number of available bytes in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . - If you pass a buffer that is a null value, returns the length of the field in bytes. + If you pass a buffer that is a null value, returns the length of the field in bytes. ]]> @@ -563,7 +563,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -614,9 +614,9 @@ public void ReadOracleTypesExample(string connectionString) returns the number of available characters in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . + returns the number of available characters in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . - If you pass a buffer that is a null value. returns the length of the field in characters. + If you pass a buffer that is a null value. returns the length of the field in characters. ]]> @@ -721,7 +721,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -764,7 +764,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -807,7 +807,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -915,7 +915,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -958,7 +958,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1001,7 +1001,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1044,7 +1044,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1087,7 +1087,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1158,7 +1158,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1193,7 +1193,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1228,7 +1228,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1263,7 +1263,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1298,7 +1298,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1333,7 +1333,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1368,7 +1368,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1403,7 +1403,7 @@ public void ReadOracleTypesExample(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1472,7 +1472,7 @@ public void ReadOracleTypesExample(string connectionString) method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, rather than retrieving each column individually. You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. @@ -1518,16 +1518,16 @@ public void ReadOracleTypesExample(string connectionString) performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. + performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. - is kana-width insensitive. + is kana-width insensitive. - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call once and then assign the results to an integer variable for use within the loop. + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call once and then assign the results to an integer variable for use within the loop. ## Examples - The following example demonstrates how to use the method. + The following example demonstrates how to use the method. ```vb Public Sub ReadOracleData(ByVal connectionString As String) @@ -1654,7 +1654,7 @@ public void ReadOracleData(string connectionString) method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, rather than retrieving each column individually. You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. @@ -1697,16 +1697,16 @@ public void ReadOracleData(string connectionString) method returns metadata about each column in the following order: + The method returns metadata about each column in the following order: |DataReader Column|Description| |-----------------------|-----------------| |ColumnName|The name of the column; this might not be unique. If the column name cannot be determined, a null value is returned. This name always reflects the most recent naming of the column in the current view or command text.| |ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.| |ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type.| -|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. `Float` and `Double` data types in Oracle are binary precision.| -|NumericScale|If is a numeric data type, the number of digits to the right of the decimal point. `Float` and `Double` data types in Oracle are binary scale.| -|DataType|Maps to the common language runtime type of .| +|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. `Float` and `Double` data types in Oracle are binary precision.| +|NumericScale|If is a numeric data type, the number of digits to the right of the decimal point. `Float` and `Double` data types in Oracle are binary scale.| +|DataType|Maps to the common language runtime type of .| |IsLong|`true` if the column contains a Binary Long Object (BLOB) that contains very long data.| |AllowDBNull|`true` if the consumer can set the column to a null value; otherwise, `false`. A column may contain null values, even if it cannot be set to a null value.| |IsUnique|`true`: No two rows in the base table-the table returned in -can have the same value in this column. **IsUnique** is guaranteed to be `true` if the column constitutes a key by itself or if there is a constraint of type UNIQUE that applies only to this column. `false`: The column can contain duplicate values in the base table. The default for this column is false.| @@ -1718,7 +1718,7 @@ public void ReadOracleData(string connectionString) A row is returned for every column in the results set. > [!NOTE] -> To ensure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. +> To ensure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. ]]> @@ -1761,7 +1761,7 @@ public void ReadOracleData(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1796,7 +1796,7 @@ public void ReadOracleData(string connectionString) to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1882,7 +1882,7 @@ public void ReadOracleData(string connectionString) method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, rather than retrieving each column individually. You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. @@ -1951,7 +1951,7 @@ public void ReadOracleData(string connectionString) and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> @@ -1994,7 +1994,7 @@ public void ReadOracleData(string connectionString) , , and so on). + To avoid raising an error, call this method to check for null column values before calling the typed Get methods (for example, , , and so on). ]]> @@ -2151,7 +2151,7 @@ public void ReadOracleData(string connectionString) is prior to the first record. Therefore, you must call to begin accessing any data. + The default position of the is prior to the first record. Therefore, you must call to begin accessing any data. More than one can be open at any given time. @@ -2199,7 +2199,7 @@ public void ReadOracleData(string connectionString) ## Remarks The property is not set until all rows are read and you close the . - and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> diff --git a/xml/System.Data.OracleClient/OracleDateTime.xml b/xml/System.Data.OracleClient/OracleDateTime.xml index bcbb0fb3fb7..5e945833e84 100644 --- a/xml/System.Data.OracleClient/OracleDateTime.xml +++ b/xml/System.Data.OracleClient/OracleDateTime.xml @@ -25,13 +25,13 @@ Represents date and time data ranging in value from January 1, 4712 BC to December 31, 4712 AD. - object, call the method. - - The minimum valid date for an structure is 1/1/0001 00:00:00. However, Oracle supports dates as early as January 1, 4712 BC. To bind BC dates, use a `String` parameter and the Oracle TO_DATE or TO_CHAR conversion functions for input and output parameters respectively. - + object, call the method. + + The minimum valid date for an structure is 1/1/0001 00:00:00. However, Oracle supports dates as early as January 1, 4712 BC. To bind BC dates, use a `String` parameter and the Oracle TO_DATE or TO_CHAR conversion functions for input and output parameters respectively. + ]]> @@ -336,26 +336,26 @@ The object to be compared. Compares this structure to the supplied object and returns an indication of their relative values. - A signed number indicating the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This structure is less than the object. - - Zero - - This structure is the same as the object. - - Greater than zero - - This structure is greater than the object, - - object is a null reference ( in Visual Basic) - + A signed number indicating the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This structure is less than the object. + + Zero + + This structure is the same as the object. + + Greater than zero + + This structure is greater than the object, + + object is a null reference ( in Visual Basic) + To be added. @@ -660,11 +660,11 @@ Represents the maximum valid date value for an structure. - structure is December, 31, 4712 AD. - + structure is December, 31, 4712 AD. + ]]> @@ -735,11 +735,11 @@ Represents the minimum valid date value for an structure. - structure is 1/1/0001 00:00:00. However, Oracle supports dates as early as January 1, 4712 BC. To bind BC dates, use a String parameter and the Oracle TO_DATE or TO_CHAR conversion functions for input and output parameters respectively. - + structure is 1/1/0001 00:00:00. However, Oracle supports dates as early as January 1, 4712 BC. To bind BC dates, use a String parameter and the Oracle TO_DATE or TO_CHAR conversion functions for input and output parameters respectively. + ]]> @@ -816,11 +816,11 @@ Represents a null value that can be assigned to the property of an instance of the structure. - structure. - + structure. + ]]> @@ -853,7 +853,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -947,7 +947,7 @@ Compares two instances of to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -978,7 +978,7 @@ Compares two instances of to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1009,7 +1009,7 @@ Performs a logical comparison of two instances of to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1040,7 +1040,7 @@ Compares two instances of to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1071,7 +1071,7 @@ Compares two instances of to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleLob.xml b/xml/System.Data.OracleClient/OracleLob.xml index 9eeaa5b717f..17e3b413f19 100644 --- a/xml/System.Data.OracleClient/OracleLob.xml +++ b/xml/System.Data.OracleClient/OracleLob.xml @@ -47,9 +47,9 @@ - After you retrieve the Oracle `LOB` value from the Oracle database into the class, you can change the `LOB` data in an open transaction and your changes are directly reflected to the database. If you retrieve the Oracle `LOB` value into an of type or and update these arrays, your changes are not reflected to the database. -- When you use the class to access a chunk of a `LOB` value, only that chunk is passed from the Oracle database to the client. When you use the method to access a chunk of a `LOB` value, the entire contents of the value are passed from the Oracle database to the client. +- When you use the class to access a chunk of a `LOB` value, only that chunk is passed from the Oracle database to the client. When you use the method to access a chunk of a `LOB` value, the entire contents of the value are passed from the Oracle database to the client. - To obtain an object, call the method. + To obtain an object, call the method. You can construct an that is NULL using this format: @@ -71,7 +71,7 @@ if (myLob == OracleLob.Null) If (myLob = OracleLob.Null) Then ``` - A NULL `LOB` behaves similarly to a zero-byte `LOB` in that succeeds and always returns zero bytes. + A NULL `LOB` behaves similarly to a zero-byte `LOB` in that succeeds and always returns zero bytes. Selecting a `LOB` column that contains a null value returns . @@ -105,7 +105,7 @@ connection.Close(); ``` > [!NOTE] -> The inherited method fails if used with character data, and an is thrown. Use the method instead. +> The inherited method fails if used with character data, and an is thrown. Use the method instead. > > Temporary `LOB`s are only closed when the connection is closed, but with pooling and under load, temporary `LOB`s do not close. This can be resolved by disposing the temporary `LOB`, by invoking `tempLob.Dispose()`. @@ -190,9 +190,9 @@ connection.Close(); mode; therefore, the `LOB` can only be read from, not written to, until the corresponding call to . To perform batch writes to the `LOB`, call with . + Opens the `LOB` in mode; therefore, the `LOB` can only be read from, not written to, until the corresponding call to . To perform batch writes to the `LOB`, call with . - Calling more than one time within the same transaction currently throws the Oracle "ORA-22293: LOB already opened in the same transaction" error. In addition, if you obtain the `LOB` using another , and the original caller has not called the method, the same error is generated. Therefore, you must call the method when you are finished using the . + Calling more than one time within the same transaction currently throws the Oracle "ORA-22293: LOB already opened in the same transaction" error. In addition, if you obtain the `LOB` using another , and the original caller has not called the method, the same error is generated. Therefore, you must call the method when you are finished using the . ]]> @@ -230,7 +230,7 @@ connection.Close(); ## Remarks To write to the `LOB`, you must have retrieved the `LOB` using the FOR UPDATE clause in the SQL SELECT statement, and you must have a local transaction started. - Calling more than one time within the same transaction currently throws the Oracle "ORA-22293: LOB already opened in the same transaction" error. In addition, if you obtain the `LOB` using another , and the original caller has not called the method, the same error is generated. Therefore, you must call the method when you are finished using the . + Calling more than one time within the same transaction currently throws the Oracle "ORA-22293: LOB already opened in the same transaction" error. In addition, if you obtain the `LOB` using another , and the original caller has not called the method, the same error is generated. Therefore, you must call the method when you are finished using the . ]]> @@ -341,7 +341,7 @@ connection.Close(); property is not a setting of the .NET Framework Data Provider for Oracle. Instead, it is the value that the Oracle Call Interface (OCI) uses when communicating with the server. Use to ensure that client-side chunks are the same size. Reading or writing in smaller chunks does not cache data, and causes a less-optimized round trip to the server, because a full packet is not received or sent. + The value returned by the property is not a setting of the .NET Framework Data Provider for Oracle. Instead, it is the value that the Oracle Call Interface (OCI) uses when communicating with the server. Use to ensure that client-side chunks are the same size. Reading or writing in smaller chunks does not cache data, and causes a less-optimized round trip to the server, because a full packet is not received or sent. ]]> @@ -378,7 +378,7 @@ connection.Close(); object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. + The properties of the new object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. ]]> @@ -676,7 +676,7 @@ connection.Close(); method before you begin performing write operations on the . + Call the method before you begin performing write operations on the . ]]> @@ -719,7 +719,7 @@ connection.Close(); does not truncate data. The `LOB` length remains the same for a `BLOB` data type, and the erased data is replaced by 0x00. `CLOB` and `NCLOB` data types are replaced by spaces. + does not truncate data. The `LOB` length remains the same for a `BLOB` data type, and the erased data is replaced by 0x00. `CLOB` and `NCLOB` data types are replaced by spaces. To write to the `LOB`, you must have retrieved the `LOB` using the FOR UPDATE clause in the SQL SELECT statement, and you must have a local transaction started. @@ -763,9 +763,9 @@ connection.Close(); . Therefore, specifying a value greater than that returned by the property succeeds; however only erases to the end of the . (Similarly, if a negative value is passed to `offset`, will succeed, but only erase starting from the beginning of the .) This behavior is different from that of the and methods, and offers the advantage of being able to erase all data from the value specified by `offset` without making an additional roundtrip to the server to verify the actual size. + The sum of the values in the `offset` and `amount` parameters can be greater than that of the size of the . Therefore, specifying a value greater than that returned by the property succeeds; however only erases to the end of the . (Similarly, if a negative value is passed to `offset`, will succeed, but only erase starting from the beginning of the .) This behavior is different from that of the and methods, and offers the advantage of being able to erase all data from the value specified by `offset` without making an additional roundtrip to the server to verify the actual size. - does not truncate data. The `LOB` length remains the same for a `BLOB` data type, and the erased data is replaced by 0x00. `CLOB` and `NCLOB` data types are replaced by spaces. + does not truncate data. The `LOB` length remains the same for a `BLOB` data type, and the erased data is replaced by 0x00. `CLOB` and `NCLOB` data types are replaced by spaces. To write to the `LOB`, you must have retrieved the `LOB` using the FOR UPDATE clause in the SQL SELECT statement, and you must have a local transaction started. @@ -1028,7 +1028,7 @@ OracleLob myLob = OracleLOB.Null; if(myLob == OracleLob.Null) ``` - A NULL `LOB` behaves similarly to a zero byte `LOB` in that succeeds and always returns zero bytes. + A NULL `LOB` behaves similarly to a zero byte `LOB` in that succeeds and always returns zero bytes. ]]> @@ -1100,7 +1100,7 @@ if(myLob == OracleLob.Null) method reads a maximum of `count` bytes from the current stream and stores them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. returns the number of bytes read. The return value is zero only if the position is currently at the end of the stream. will block until at least one byte of data can be read, in the event that no data is available. returns 0 if you attempt to read from a `LOB` when the current position is at the end of `LOB`. can return fewer bytes than requested even if the end of the stream has not been reached. + The method reads a maximum of `count` bytes from the current stream and stores them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. returns the number of bytes read. The return value is zero only if the position is currently at the end of the stream. will block until at least one byte of data can be read, in the event that no data is available. returns 0 if you attempt to read from a `LOB` when the current position is at the end of `LOB`. can return fewer bytes than requested even if the end of the stream has not been reached. The .NET Framework Data Provider for Oracle handles all `CLOB` and `NCLOB` data as Unicode. Therefore, when accessing `CLOB` and `NCLOB` data types, you are always dealing with the number of bytes, where each character is 2 bytes. For example, if a string of text containing three characters is saved as an `NCLOB` on an Oracle server where the character set is 4 bytes per character, and you perform a `Read` operation, you specify the length of the string as 6 bytes, although it is stored as 12 bytes on the server. @@ -1161,7 +1161,7 @@ OracleLob myLob = OracleLob.Null; if (myLob == OracleLob.Null) ``` - A NULL `LOB` behaves similarly to a zero byte `LOB` in that succeeds and always returns zero bytes. + A NULL `LOB` behaves similarly to a zero byte `LOB` in that succeeds and always returns zero bytes. ]]> @@ -1251,7 +1251,7 @@ if (myLob == OracleLob.Null) ## Remarks An attempt to increase the length of the stream fails, and returns "Message: ORA-22926: specified trim length is greater than current LOB value's length" from the Oracle server. - A stream must support both writing and seeking for to function. + A stream must support both writing and seeking for to function. The .NET Framework Data Provider for Oracle handles all `CLOB` and `NCLOB` data as Unicode. Therefore, when accessing `CLOB` and `NCLOB` data types, you are always dealing with the number of bytes, where each character is 2 bytes. For example, if a string of text containing three characters is saved as an `NCLOB` on an Oracle server where the character set is 4 bytes per character, and you perform a `SetLength` operation, you specify the length of the string as 6 bytes, although it is stored as 12 bytes on the server. @@ -1296,10 +1296,10 @@ if (myLob == OracleLob.Null) data types, returns the entire underlying data as a contiguous array of type `Byte[]`. For and data types, returns all the data as a `String` data type. For null data, returns . By comparing the returned values, you can distinguish among empty data, null data, and data. + For data types, returns the entire underlying data as a contiguous array of type `Byte[]`. For and data types, returns all the data as a `String` data type. For null data, returns . By comparing the returned values, you can distinguish among empty data, null data, and data. > [!NOTE] -> A benefit of using `LOB` data types is the capability to retrieve large amounts of data in chunks at the client. However, when you use , you obtain all the data for the `LOB` column as one contiguous chunk, which can significantly increase application overhead. +> A benefit of using `LOB` data types is the capability to retrieve large amounts of data in chunks at the client. However, when you use , you obtain all the data for the `LOB` column as one contiguous chunk, which can significantly increase application overhead. ]]> diff --git a/xml/System.Data.OracleClient/OracleMonthSpan.xml b/xml/System.Data.OracleClient/OracleMonthSpan.xml index 005f88c38bc..915d105bb88 100644 --- a/xml/System.Data.OracleClient/OracleMonthSpan.xml +++ b/xml/System.Data.OracleClient/OracleMonthSpan.xml @@ -25,13 +25,13 @@ Represents a time interval in months and corresponds to the Oracle 9i data type. - object, call the method. - + object, call the method. + ]]> @@ -143,28 +143,28 @@ The object to be compared. Compares this structure to the supplied object and returns an indication of their relative values. - A signed number indicating the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference (). - + A signed number indicating the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference (). + To be added. @@ -423,11 +423,11 @@ Represents the maximum valid date value for an structure. - @@ -452,11 +452,11 @@ Represents the minimum valid date value for an structure. - @@ -510,11 +510,11 @@ Represents a null value that can be assigned to the property of an instance of the structure. - structure. - + structure. + ]]> @@ -547,7 +547,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -641,7 +641,7 @@ Compares two instances of to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -672,7 +672,7 @@ Compares two instances of to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -703,7 +703,7 @@ Performs a logical comparison of two instances of to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -734,7 +734,7 @@ Compares two instances of to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -765,7 +765,7 @@ Compares two instances of to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleNumber.xml b/xml/System.Data.OracleClient/OracleNumber.xml index d2b9ff8c6b3..23e18aece6b 100644 --- a/xml/System.Data.OracleClient/OracleNumber.xml +++ b/xml/System.Data.OracleClient/OracleNumber.xml @@ -25,13 +25,13 @@ Represents a fixed precision and scale numeric value between -10 27 -1 and 10 27 -1 to be stored in or retrieved from a database. - object, call the method. - - Oracle numeric data types can store up to 27 decimal digits of precision. When converting Oracle numeric values to common language runtime data types, the Oracle value might be too large. Conversely, when converting a numeric value of a common language runtime data types to an , the numeric value may be either too large or too high precision for the . Either of these cases will cause an Oracle ORA-22053 overflow error. If your Oracle database might contain large values, you should use the data type. You can then convert to the common language runtime data type explicitly, and catch or handle any errors. - + object, call the method. + + Oracle numeric data types can store up to 27 decimal digits of precision. When converting Oracle numeric values to common language runtime data types, the Oracle value might be too large. Conversely, when converting a numeric value of a common language runtime data types to an , the numeric value may be either too large or too high precision for the . Either of these cases will cause an Oracle ORA-22053 overflow error. If your Oracle database might contain large values, you should use the data type. You can then convert to the common language runtime data type explicitly, and catch or handle any errors. + ]]> @@ -379,24 +379,24 @@ The object to be compared. Compares this instance of the structure to the supplied object and returns an indication of their relative values. - A signed number indicating the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object, or the object is a null reference ( in Visual Basic) - + A signed number indicating the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object, or the object is a null reference ( in Visual Basic) + To be added. @@ -504,11 +504,11 @@ Returns the value e-2.718. - is useful for performing scientific calculations or as a parameter value. - + is useful for performing scientific calculations or as a parameter value. + ]]> @@ -970,11 +970,11 @@ A constant representing the largest possible value for precision comparison. - @@ -999,11 +999,11 @@ A constant representing the maximum value for scale comparison. - @@ -1028,11 +1028,11 @@ A constant representing the maximum value of an structure. - (Double) constructor is: 9.99999999999999E+125. - + (Double) constructor is: 9.99999999999999E+125. + ]]> @@ -1086,11 +1086,11 @@ A constant representing the minimum value for scale comparison. - @@ -1115,11 +1115,11 @@ Returns the value -1. - is useful for performing calculations or as a parameter value. - + is useful for performing calculations or as a parameter value. + ]]> @@ -1144,11 +1144,11 @@ A constant representing the minimum value for an structure. - @@ -1309,11 +1309,11 @@ Returns the value 1. - is useful for performing calculations or as a parameter value. - + is useful for performing calculations or as a parameter value. + ]]> @@ -1345,7 +1345,7 @@ Calculates the sum of the two structures. A new structure whose property contains the sum. - ]]> + ]]> @@ -1376,7 +1376,7 @@ Calculates the results of dividing the first structure by the second. A new structure whose property contains the results of the division. - ]]> + ]]> @@ -1407,7 +1407,7 @@ Performs a logical comparison of the two structures to determine whether they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -1517,25 +1517,25 @@ Converts the structure to . A new structure whose value equals the of the structure. - and converts it to an . - -```csharp -//Create OracleNumber and cast it to an Int32. -OracleNumber n = new OracleNumber(42); -Int32 i = (Int32)n; -Console.WriteLine(i); -``` - -```vb -'Create OracleNumber and cast it to an Int32. - Dim n As OracleNumber = New OracleNumber(42) - Dim i As Int32 = (Int32)n - Console.WriteLine(i)) -``` - + and converts it to an . + +```csharp +//Create OracleNumber and cast it to an Int32. +OracleNumber n = new OracleNumber(42); +Int32 i = (Int32)n; +Console.WriteLine(i); +``` + +```vb +'Create OracleNumber and cast it to an Int32. + Dim n As OracleNumber = New OracleNumber(42) + Dim i As Int32 = (Int32)n + Console.WriteLine(i)) +``` + ]]> @@ -1702,7 +1702,7 @@ Console.WriteLine(i); Performs a logical comparison of two structures to determine whether the first is greater than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1733,7 +1733,7 @@ Console.WriteLine(i); Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1764,7 +1764,7 @@ Console.WriteLine(i); Performs a logical comparison of the two parameters to determine whether they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -1795,7 +1795,7 @@ Console.WriteLine(i); Performs a logical comparison of two structures to determine whether the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1826,7 +1826,7 @@ Console.WriteLine(i); Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1857,7 +1857,7 @@ Console.WriteLine(i); Calculates the remainder left over from dividing an structure by a second structure. A new structure whose property contains the modulus of the division. - ]]> + ]]> @@ -1888,7 +1888,7 @@ Console.WriteLine(i); Calculates the product of two structures. A new structure whose property contains the product of the multiplication. - ]]> + ]]> @@ -1919,7 +1919,7 @@ Console.WriteLine(i); Calculates the result of subtracting the second structure from the first. A new structure whose property contains the results of the subtraction. - ]]> + ]]> @@ -1948,7 +1948,7 @@ Console.WriteLine(i); Negates the structure. A new structure whose value contains the results of the negation. - ]]> + ]]> @@ -1999,11 +1999,11 @@ Console.WriteLine(i); Returns the value of pi-3.1415926535897932384626433832795028842. - is useful for performing calculations or as a parameter value. - + is useful for performing calculations or as a parameter value. + ]]> @@ -2375,11 +2375,11 @@ Console.WriteLine(i); Truncates the specified structure's value to the desired position. A structure with its truncated to the specified . - @@ -2405,11 +2405,11 @@ Console.WriteLine(i); Gets the value of the structure. This property is read-only. A number in the range -79,228,162,514,264,337,593,543,950,335 through 79,228,162,514, 264,337,593,543,950,335. - method to retrieve such values. - + method to retrieve such values. + ]]> @@ -2434,11 +2434,11 @@ Console.WriteLine(i); Returns the value 0. - is useful for performing calculations or as a parameter value. - + is useful for performing calculations or as a parameter value. + ]]> diff --git a/xml/System.Data.OracleClient/OracleParameter.xml b/xml/System.Data.OracleClient/OracleParameter.xml index 805656c7a25..8541db38cf7 100644 --- a/xml/System.Data.OracleClient/OracleParameter.xml +++ b/xml/System.Data.OracleClient/OracleParameter.xml @@ -340,7 +340,7 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); and displays the . + The following example creates an and displays the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter4/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleParameter/.ctor/source3.vb" id="Snippet1"::: @@ -394,11 +394,11 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . - For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -456,7 +456,7 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); ## Remarks If the is output, and execution of the associated does not return a value, the contains a null value. - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call on the . + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call on the . @@ -669,9 +669,9 @@ public void CreateOracleParameter() and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -792,7 +792,7 @@ public void CreateOracleDbParameter() or properties has no effect. + Setting the or properties has no effect. ]]> @@ -821,7 +821,7 @@ public void CreateOracleDbParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -853,7 +853,7 @@ public void CreateOracleDbParameter() and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -907,7 +907,7 @@ public void CreateOracleDbParameter() or properties has no effect. + Setting the or properties has no effect. ]]> @@ -949,19 +949,19 @@ public void CreateOracleDbParameter() affects only the input value of a parameter. Return values and output parameters are not affected by this property. + Setting affects only the input value of a parameter. Return values and output parameters are not affected by this property. The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. - For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. + For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. For bidirectional and output parameters, and return values, you must set the value of Size. This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. - For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. + For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. @@ -1083,16 +1083,16 @@ public void CreateOracleDbParameter() is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): ```tsql ((@IsNull_FieldName = 1 AND FieldName IS NULL) OR (FieldName = @Original_FieldName)) ``` - If for the field is false, generates the following WHERE clause: + If for the field is false, generates the following WHERE clause: ```tsql FieldName = @OriginalFieldName @@ -1140,7 +1140,7 @@ FieldName = @OriginalFieldName during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. + This property is used by the during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. @@ -1276,13 +1276,13 @@ public void CreateOracleParameter() ## Remarks For input parameters, the value is bound to the that is sent to the server. For output and return-value parameters, the value is set on completion of the and after the is closed. - For an input parameter, can be set to an object of either a Microsoft .NET Framework data type or an Oracle data type (for example, an or ). + For an input parameter, can be set to an object of either a Microsoft .NET Framework data type or an Oracle data type (for example, an or ). When you send a null parameter value to the server, you must specify DBNull, not null. A null value in the system is an empty object that has no value. DBNull is used to represent null values. If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - The , , and properties of a parameter can be inferred by setting Value. Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, Size does not contain inferred value after statement execution. + The , , and properties of a parameter can be inferred by setting Value. Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, Size does not contain inferred value after statement execution. The `InputOutput`, `Output`, and `ReturnValue` values used by the Value property will be Microsoft .NET Framework data types, unless the input value was an Oracle data type (for example, or ). This does not apply to REF CURSOR, BFILE, or LOB data types. diff --git a/xml/System.Data.OracleClient/OracleParameterCollection.xml b/xml/System.Data.OracleClient/OracleParameterCollection.xml index 26c94fca81d..3e32c22e015 100644 --- a/xml/System.Data.OracleClient/OracleParameterCollection.xml +++ b/xml/System.Data.OracleClient/OracleParameterCollection.xml @@ -270,7 +270,7 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero. If you don't perform this conversion, the compiler will assume you are attempting to call the `OracleParameterCollection.Add` (`string`, `OracleType`) overload. + Use caution when using this overload of the method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero. If you don't perform this conversion, the compiler will assume you are attempting to call the `OracleParameterCollection.Add` (`string`, `OracleType`) overload. ]]> @@ -723,7 +723,7 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID method, which supports a simple iteration over a collection by a .NET data provider. + Exposes the method, which supports a simple iteration over a collection by a .NET data provider. ]]> @@ -1120,7 +1120,7 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. + The following example searches for an with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.this1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleParameterCollection/Item/source1.vb" id="Snippet1"::: diff --git a/xml/System.Data.OracleClient/OraclePermission.xml b/xml/System.Data.OracleClient/OraclePermission.xml index fe82eb421c7..212fd810d9d 100644 --- a/xml/System.Data.OracleClient/OraclePermission.xml +++ b/xml/System.Data.OracleClient/OraclePermission.xml @@ -61,7 +61,7 @@ This type is deprecated and will be removed in a future version of .NET Framework. For more information, see [Oracle and ADO.NET](/dotnet/framework/data/adonet/oracle-and-adonet). - The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. + The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). @@ -182,7 +182,7 @@ enumeration takes precedence over the property. Therefore, if you set to false, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to false, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> diff --git a/xml/System.Data.OracleClient/OraclePermissionAttribute.xml b/xml/System.Data.OracleClient/OraclePermissionAttribute.xml index af0baaf4be1..6c67e26c94b 100644 --- a/xml/System.Data.OracleClient/OraclePermissionAttribute.xml +++ b/xml/System.Data.OracleClient/OraclePermissionAttribute.xml @@ -171,7 +171,7 @@ . + Multiple connection strings may be identified. You may also provide additional connection string restrictions using . ]]> diff --git a/xml/System.Data.OracleClient/OracleRowUpdatedEventArgs.xml b/xml/System.Data.OracleClient/OracleRowUpdatedEventArgs.xml index eba8163a0ce..748694d0ab0 100644 --- a/xml/System.Data.OracleClient/OracleRowUpdatedEventArgs.xml +++ b/xml/System.Data.OracleClient/OracleRowUpdatedEventArgs.xml @@ -18,43 +18,43 @@ Provides data for the event. This class cannot be inherited. - event is raised when an to a row is completed. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - `Event Arguments: (command=OracleCommand commandType=2status=0)` - - The event returns this output: - - `Event Arguments: (command= OracleCommend commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0)` - + event is raised when an to a row is completed. + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows how to use both the and events. + + The event returns this output: + + `Event Arguments: (command=OracleCommand commandType=2status=0)` + + The event returns this output: + + `Event Arguments: (command= OracleCommend commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0)` + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleRowUpdatedEventArgs/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleRowUpdatedEventArgs/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleRowUpdatedEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data.OracleClient/OracleRowUpdatingEventArgs.xml b/xml/System.Data.OracleClient/OracleRowUpdatingEventArgs.xml index 5f2c3db3715..c67b3737b28 100644 --- a/xml/System.Data.OracleClient/OracleRowUpdatingEventArgs.xml +++ b/xml/System.Data.OracleClient/OracleRowUpdatingEventArgs.xml @@ -18,43 +18,43 @@ Provides data for the event. - event is raised before an to a row. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - `Event Arguments: (command=OracleCommand commandType=2 status=0)` - - The event returns this output: - - `Event Arguments: (command=OracleCommand commandType=2 recordsAffected=1 row=DataRow[37] status=0)` - + event is raised before an to a row. + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows how to use both the and events. + + The event returns this output: + + `Event Arguments: (command=OracleCommand commandType=2 status=0)` + + The event returns this output: + + `Event Arguments: (command=OracleCommand commandType=2 recordsAffected=1 row=DataRow[37] status=0)` + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleRowUpdatingEventArgs/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleRowUpdatingEventArgs/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleRowUpdatingEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data.OracleClient/OracleString.xml b/xml/System.Data.OracleClient/OracleString.xml index 2e3059fa40b..c4c6e2e747e 100644 --- a/xml/System.Data.OracleClient/OracleString.xml +++ b/xml/System.Data.OracleClient/OracleString.xml @@ -28,7 +28,7 @@ object, call the method. + To obtain an object, call the method. @@ -585,7 +585,7 @@ public class Class1 { Concatenates the two specified structures. An containing the newly concatenated value representing the contents of the two parameters. - ]]> + ]]> @@ -616,7 +616,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -676,7 +676,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -707,7 +707,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -765,7 +765,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -796,7 +796,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -827,7 +827,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleTimeSpan.xml b/xml/System.Data.OracleClient/OracleTimeSpan.xml index a6c80a416c4..971336df2d3 100644 --- a/xml/System.Data.OracleClient/OracleTimeSpan.xml +++ b/xml/System.Data.OracleClient/OracleTimeSpan.xml @@ -25,13 +25,13 @@ Represents a time interval and corresponds to the Oracle 9i data type. - object, call the method. - + object, call the method. + ]]> @@ -230,24 +230,24 @@ The object to be compared. Compares this structure to the supplied object and returns an indication of their relative values. - A signed number indicating the relative values of the instance of the structure and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object, or the object is a null reference ( in Visual Basic). - + A signed number indicating the relative values of the instance of the structure and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object, or the object is a null reference ( in Visual Basic). + To be added. @@ -552,11 +552,11 @@ Represents the maximum valid date value for an structure. - , use the Oracle SELECT TO_CHAR statement. For more information about the ranges supported by the Oracle 9i `INTERVAL DAY TO SECOND` data type, see your Oracle documentation. - + , use the Oracle SELECT TO_CHAR statement. For more information about the ranges supported by the Oracle 9i `INTERVAL DAY TO SECOND` data type, see your Oracle documentation. + ]]> @@ -627,11 +627,11 @@ Represents the minimum valid date value for an structure. - , use the Oracle SELECT TO_CHAR statement. For more information about the ranges supported by the Oracle 9i `INTERVAL DAY TO SECOND` data type, see your Oracle documentation. - + , use the Oracle SELECT TO_CHAR statement. For more information about the ranges supported by the Oracle 9i `INTERVAL DAY TO SECOND` data type, see your Oracle documentation. + ]]> @@ -685,11 +685,11 @@ Represents a null value that can be assigned to the property of an instance of the structure. - structure. - + structure. + ]]> @@ -722,7 +722,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -816,7 +816,7 @@ Compares two instances of to determine whether the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -847,7 +847,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -878,7 +878,7 @@ Performs a logical comparison of two instances of to determine whether they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -909,7 +909,7 @@ Compares two instances of to determine whether the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -940,7 +940,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleTransaction.xml b/xml/System.Data.OracleClient/OracleTransaction.xml index 2d40e8d2469..6ea4f89d362 100644 --- a/xml/System.Data.OracleClient/OracleTransaction.xml +++ b/xml/System.Data.OracleClient/OracleTransaction.xml @@ -31,19 +31,19 @@ Represents a transaction to be made in the database. - object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. - + object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. + + + +## Examples + The following example creates an and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleConnection.BeginTransaction/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Commit/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Commit/source.vb" id="Snippet1"::: + ]]> @@ -79,21 +79,21 @@ Commits the SQL database transaction. - and an . It also demonstrates how to use the , , and methods. - + and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. @@ -120,11 +120,11 @@ Specifies the object associated with the transaction. The object associated with the transaction. - @@ -227,13 +227,13 @@ Specifies the for this transaction. The for this transaction. The default is . - applies to the entire transaction. - + applies to the entire transaction. + ]]> @@ -267,26 +267,26 @@ Rolls back a transaction from a pending state. - has been called, but before is called). - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. - + has been called, but before is called). + + + +## Examples + The following example creates an and an . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleConnection.BeginTransaction1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. diff --git a/xml/System.Data.Services.Client/ChangeOperationResponse.xml b/xml/System.Data.Services.Client/ChangeOperationResponse.xml index c78ac73fee2..46e7a002c2d 100644 --- a/xml/System.Data.Services.Client/ChangeOperationResponse.xml +++ b/xml/System.Data.Services.Client/ChangeOperationResponse.xml @@ -18,112 +18,112 @@ Results returned after a call to when enumerating operation responses returned by the class. - objects are not intended to be constructed directly by a user of this library. Instead, references are returned when enumerating the operation responses returned via the enumerator on the class. - - submits pending changes to the data service collected by the since the last call to . Changes are added to the context by calling , , , , , , and similar methods. - - returns a that represents the response to all operations sent to the data service. The object includes a sequence of objects that, in turn, contain a sequence of or instances that represent the changes that were persisted or attempted. - - - -## Examples - The following code shows how to process the results of a call to . - -``` -DataServiceContext service = new DataServiceContext(new Uri("http://myserviceroot")); - -// Do insert, update, delete, or attach operations. - -DataServiceResponse dsr; - -try -{ - dsr = service.SaveChanges(SaveChangesOptions.Batch); - // Or service.SaveChanges(SaveChangesOptions.ContinueOnError); - //Or service.SaveChanges(); - // If there are no errors during save changes, process the results: - - if (dsr.IsBatchResponse) - { - /*inspect HTTP artifacts associated with the entire batch: - dsr.BatchHeaders, dsr.BatchStatusCode*/ } - - foreach (ChangeOperationResponse cor in dsr) - { - - if (cor.Descriptor is EntityDescriptor) - { - EntityDescriptor ed = (EntityDescriptor)cor.Descriptor; - // This should be the case if - // SaveChanges did not throw an exception. - - // After an entity is processed by SaveChanges, - // it is always moved to the unchanged state. - System.Diagnostics.Debug.Assert( - ed.State == EntityStates.Unchanged); - // This shows that the state should be unchanged if - // the result is success. - - //process the entity in the response payload: ed.Entity - } - else if (cor.Descriptor is LinkDescriptor) - { - LinkDescriptor ld = (LinkDescriptor)cor.Descriptor; - // This should be the case if SaveChanges did not throw an exception. - - // After an entity is processed by SaveChanges it - // is always moved to the unchanged state. - System.Diagnostics.Debug.Assert( - ld.State == EntityStates.Unchanged); - // The state should be unchanged if the result is success. - - //process the link in the response payload: ld.Source, - // ld.SourceProperty, or ld.Target. - } - } - -} -catch (DataServiceSaveException se) -{ - // Error while saving changes - dsr = se.Response; - - if (dsr.IsBatchResponse) - { - /*inspect HTTP artifacts associated with the entire batch: - dsr.BatchHeaders, dsr.BatchStatusCode*/ -} -} - - foreach (ChangeOperationResponse cor in dsr) - { - if (cor.Error != null) - { - //process error - } - else - { - // same success case processing as in the loop over DSRs results in - // the try block. You could put that processing in a method - // and call it from here. - } - } - -} - - catch(Exception) - { - // Error while saving changes, but not thrown by the client library. - - // Process ArgumentException, InvalidOperationException, or similar. -} -} - -``` - + objects are not intended to be constructed directly by a user of this library. Instead, references are returned when enumerating the operation responses returned via the enumerator on the class. + + submits pending changes to the data service collected by the since the last call to . Changes are added to the context by calling , , , , , , and similar methods. + + returns a that represents the response to all operations sent to the data service. The object includes a sequence of objects that, in turn, contain a sequence of or instances that represent the changes that were persisted or attempted. + + + +## Examples + The following code shows how to process the results of a call to . + +``` +DataServiceContext service = new DataServiceContext(new Uri("http://myserviceroot")); + +// Do insert, update, delete, or attach operations. + +DataServiceResponse dsr; + +try +{ + dsr = service.SaveChanges(SaveChangesOptions.Batch); + // Or service.SaveChanges(SaveChangesOptions.ContinueOnError); + //Or service.SaveChanges(); + // If there are no errors during save changes, process the results: + + if (dsr.IsBatchResponse) + { + /*inspect HTTP artifacts associated with the entire batch: + dsr.BatchHeaders, dsr.BatchStatusCode*/ } + + foreach (ChangeOperationResponse cor in dsr) + { + + if (cor.Descriptor is EntityDescriptor) + { + EntityDescriptor ed = (EntityDescriptor)cor.Descriptor; + // This should be the case if + // SaveChanges did not throw an exception. + + // After an entity is processed by SaveChanges, + // it is always moved to the unchanged state. + System.Diagnostics.Debug.Assert( + ed.State == EntityStates.Unchanged); + // This shows that the state should be unchanged if + // the result is success. + + //process the entity in the response payload: ed.Entity + } + else if (cor.Descriptor is LinkDescriptor) + { + LinkDescriptor ld = (LinkDescriptor)cor.Descriptor; + // This should be the case if SaveChanges did not throw an exception. + + // After an entity is processed by SaveChanges it + // is always moved to the unchanged state. + System.Diagnostics.Debug.Assert( + ld.State == EntityStates.Unchanged); + // The state should be unchanged if the result is success. + + //process the link in the response payload: ld.Source, + // ld.SourceProperty, or ld.Target. + } + } + +} +catch (DataServiceSaveException se) +{ + // Error while saving changes + dsr = se.Response; + + if (dsr.IsBatchResponse) + { + /*inspect HTTP artifacts associated with the entire batch: + dsr.BatchHeaders, dsr.BatchStatusCode*/ +} +} + + foreach (ChangeOperationResponse cor in dsr) + { + if (cor.Error != null) + { + //process error + } + else + { + // same success case processing as in the loop over DSRs results in + // the try block. You could put that processing in a method + // and call it from here. + } + } + +} + + catch(Exception) + { + // Error while saving changes, but not thrown by the client library. + + // Process ArgumentException, InvalidOperationException, or similar. +} +} + +``` + ]]> diff --git a/xml/System.Data.Services.Client/DataServiceClientException.xml b/xml/System.Data.Services.Client/DataServiceClientException.xml index e2c37d98577..d69291ea4ea 100644 --- a/xml/System.Data.Services.Client/DataServiceClientException.xml +++ b/xml/System.Data.Services.Client/DataServiceClientException.xml @@ -65,8 +65,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -106,8 +106,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -175,8 +175,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Data.Services.Client/DataServiceCollection`1.xml b/xml/System.Data.Services.Client/DataServiceCollection`1.xml index ec25952867b..f786d3a9367 100644 --- a/xml/System.Data.Services.Client/DataServiceCollection`1.xml +++ b/xml/System.Data.Services.Client/DataServiceCollection`1.xml @@ -28,14 +28,14 @@ class to support binding data to controls in client applications. This class inherits from the class, which implements the interface and is the primary data binding mechanism for Windows Presentation Foundation (WPF) and Silverlight-based applications. + WCF Data Services provides the class to support binding data to controls in client applications. This class inherits from the class, which implements the interface and is the primary data binding mechanism for Windows Presentation Foundation (WPF) and Silverlight-based applications. - You can load an binding collection by using any collection that implements the interface. Items loaded into the binding collection must implement the interface. For more information, see [Binding Data to Controls](/dotnet/framework/data/wcf/binding-data-to-controls-wcf-data-services). + You can load an binding collection by using any collection that implements the interface. Items loaded into the binding collection must implement the interface. For more information, see [Binding Data to Controls](/dotnet/framework/data/wcf/binding-data-to-controls-wcf-data-services). ## Examples - The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, an is created based on the result of a query that returns customers with related objects, filtered by country/region. This result is bound to the property of the that is the root layout control for the WPF window. + The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, an is created based on the result of a query that returns customers with related objects, filtered by country/region. This result is bound to the property of the that is the root layout control for the WPF window. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml.cs" id="Snippetwpfdatabinding"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml.vb" id="Snippetwpfdatabinding"::: @@ -84,7 +84,7 @@ . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . Automatic change tracking begins after items are loaded into the collection. @@ -121,9 +121,9 @@ collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. + The collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . ]]> @@ -158,9 +158,9 @@ to which entity objects can be added without executing a query against the service or when an is not available. + Use this constructor to create an empty to which entity objects can be added without executing a query against the service or when an is not available. - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . ]]> @@ -197,9 +197,9 @@ . Use this class constructor and supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . Use this class constructor and supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - The collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. + The collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. ]]> @@ -240,9 +240,9 @@ to which entity objects can be added without executing a query against the service or when an is not available. + Use this constructor to create an empty to which entity objects can be added without executing a query against the service or when an is not available. - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . ]]> @@ -287,7 +287,7 @@ ## Remarks The `entityChanged` and `collectionChanged` functions are invoked by the and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior still occurs. - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . ]]> @@ -326,9 +326,9 @@ . Use this class constructor to supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + By default, automatic change tracking is enabled for a . Use this class constructor to supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - The must be supplied when `items` is not a or that has a reference to a instance. + The must be supplied when `items` is not a or that has a reference to a instance. The `entityChanged` and `collectionChanged` functions are invoked by the and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior will still occur. @@ -401,14 +401,14 @@ property returns a link that is used to access the next set of paged results when paging is enabled in the data service. For more information, see [Configuring the Data Service](/dotnet/framework/data/wcf/configuring-the-data-service-wcf-data-services). + The property returns a link that is used to access the next set of paged results when paging is enabled in the data service. For more information, see [Configuring the Data Service](/dotnet/framework/data/wcf/configuring-the-data-service-wcf-data-services). - When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. + When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. ## Examples - The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, a is created based on the result of a query that returns customers, filtered by country/region. All of the pages of this paged result are loaded, along with the related orders, and are bound to the property of the that is the root layout control for the WPF window. For more information, see [How to: Bind Data to Windows Presentation Foundation Elements](/dotnet/framework/data/wcf/bind-data-to-wpf-elements-wcf-data-services). + The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, a is created based on the result of a query that returns customers, filtered by country/region. All of the pages of this paged result are loaded, along with the related orders, and are bound to the property of the that is the root layout control for the WPF window. For more information, see [How to: Bind Data to Windows Presentation Foundation Elements](/dotnet/framework/data/wcf/bind-data-to-wpf-elements-wcf-data-services). :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf3.xaml.cs" id="Snippetbindpageddata"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf3.xaml.vb" id="Snippetbindpageddata"::: @@ -442,9 +442,9 @@ method can only be called when is the root collection. + The method can only be called when is the root collection. - When the method is called on a collection that is a root collection, tracking is also stopped for all related objects in the data graph. + When the method is called on a collection that is a root collection, tracking is also stopped for all related objects in the data graph. ]]> @@ -478,7 +478,7 @@ method to prevent items from being automatically added to the collection. + When you are manually tracking changes to the collection, you must override the method to prevent items from being automatically added to the collection. ]]> @@ -520,9 +520,9 @@ method attaches all objects in the collection, if they are not already attached to the that is associated with the . + Calling the method attaches all objects in the collection, if they are not already attached to the that is associated with the . - When an object is attached by using the method, all related objects are also attached. + When an object is attached by using the method, all related objects are also attached. ]]> @@ -554,9 +554,9 @@ method attaches the object, if it is not already attached to the that is associated with the . + Calling the method attaches the object, if it is not already attached to the that is associated with the . - When an object is attached by using the method, all related objects are also attached. + When an object is attached by using the method, all related objects are also attached. ]]> diff --git a/xml/System.Data.Services.Client/DataServiceContext.xml b/xml/System.Data.Services.Client/DataServiceContext.xml index 2ff2014013f..e975021797a 100644 --- a/xml/System.Data.Services.Client/DataServiceContext.xml +++ b/xml/System.Data.Services.Client/DataServiceContext.xml @@ -103,16 +103,16 @@ that a new link exists between the related source and target objects and that the link is represented by the specified source property. The adds this link to the set of newly created links that will be sent to the data service on the next call to . + Notifies the that a new link exists between the related source and target objects and that the link is represented by the specified source property. The adds this link to the set of newly created links that will be sent to the data service on the next call to . - Links are one-way relationships. Because associations are bi-directional, in a one-to-one association you must call either again to create the reverse link, and in a many-to-one association you must call to create a reference link to the "one" end of the association. + Links are one-way relationships. Because associations are bi-directional, in a one-to-one association you must call either again to create the reverse link, and in a many-to-one association you must call to create a reference link to the "one" end of the association. The target object must be of the type identified by the `sourceProperty` parameter or a subtype of the type. ## Examples - The following example shows how to use the and methods to create links that define relationships. In this example, the navigation properties on the `Order_Details` object are also explicitly set. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . + The following example shows how to use the and methods to create links that define relationships. In this example, the navigation properties on the `Order_Details` object are also explicitly set. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddorderdetailtoorder"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddorderdetailtoorder"::: @@ -159,7 +159,7 @@ in the state. The will try to insert the object by HTTP POST on the next call to . This method does not add objects related to the specified entity to the . Each object must be added through a separate call to . + The object is put into the tracking set of the in the state. The will try to insert the object by HTTP POST on the next call to . This method does not add objects related to the specified entity to the . Each object must be added through a separate call to . The method does not validate that the entity set specified is in the data service associated with the or that the added object has the required properties needed to be added to the specified `entity set`. @@ -206,7 +206,7 @@ method to add a related object instead of calling these three methods: , , . + You can call the method to add a related object instead of calling these three methods: , , . ]]> @@ -477,7 +477,7 @@ object contains the URI that, when executed, returns the next page of data in the query result. + The supplied object contains the URI that, when executed, returns the next page of data in the query result. ]]> @@ -520,12 +520,12 @@ ## Remarks The returned object is used to determine when the asynchronous operation has completed. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services). - The method uses the same semantics as , however this method asynchronously sends the request so that this call does not block processing while waiting for the results from the service. According to the standard begin-end asynchronous pattern, the provided callback is invoked when query results are retrieved. + The method uses the same semantics as , however this method asynchronously sends the request so that this call does not block processing while waiting for the results from the service. According to the standard begin-end asynchronous pattern, the provided callback is invoked when query results are retrieved. ## Examples - The following example shows how to execute an asynchronous query by calling the method to start the query. The inline delegate calls the method to display the query results. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . + The following example shows how to execute an asynchronous query by calling the method to start the query. The inline delegate calls the method to display the query results. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetexecutequeryasync"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetexecutequeryasync"::: @@ -575,7 +575,7 @@ ## Remarks The returned object is used to determine when the asynchronous operation has completed. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services). - The queries are specified as instances. Returns a that represents the response of the batch request as a whole. Individual query responses are represented as objects that can be accessed by enumerating the instance. + The queries are specified as instances. Returns a that represents the response of the batch request as a whole. Individual query responses are represented as objects that can be accessed by enumerating the instance. When this method returns, all of the HTTP response for the batch request has been read from the network stream but the responses have not been processed. No identity resolution or object materialization occurs for a specified entity in the response until it is enumerated. @@ -616,7 +616,7 @@ method asynchronously requests a data stream that contains the binary property of the requested `entity`. + The method asynchronously requests a data stream that contains the binary property of the requested `entity`. In the AtomPub protocol, the `entity` is a Media Link Entry and the binary property is the associated Media Resource. @@ -728,7 +728,7 @@ object contains the URI that, when executed, returns the next page of data in the query result. + The supplied object contains the URI that, when executed, returns the next page of data in the query result. ]]> @@ -816,9 +816,9 @@ by calling the , , , , , , , or . + Changes are added to the by calling the , , , , , , , or . - Changes are sent to the data service, as with the method, one change operation per HTTP request. + Changes are sent to the data service, as with the method, one change operation per HTTP request. If an error occurs while processing an operation, no additional operations are processed by the data service. Instead, a response is generated telling the client what operations were executed, the results, and which operations were not tried because of an error. @@ -857,7 +857,7 @@ by calling the , , , , , , , or . + Changes are added to the by calling the , , , , , , , or . If is set, all pending changes are included in a single change set in a batch and submitted to the data service in a single HTTP request. This requires that the target service supports batching. @@ -865,7 +865,7 @@ - Changes are sent to the data service such as in the method: one operation to one HTTP request. -- The is always 200. +- The is always 200. - The property returns an empty collection. @@ -1121,7 +1121,7 @@ ## Remarks Once an object is detached, it is no longer tracked by the . - The method can be called to detach any object, regardless of its . + The method can be called to detach any object, regardless of its . After detaching the specified entity, this method also detaches any links related to the entity. @@ -1203,12 +1203,12 @@ ## Remarks According to the standard begin-end asynchronous pattern, the provided callback is invoked when query results are retrieved. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services). - When the callback is invoked, all results have been read from the HTTP stream, but they have not been processed; no local user-facing objects have been materialized or modified and identity resolution has not occurred. When is invoked, a is created and returned but the results still have not been processed. Identity resolution, object materialization, and manipulation occur only when the user enumerates the results. + When the callback is invoked, all results have been read from the HTTP stream, but they have not been processed; no local user-facing objects have been materialized or modified and identity resolution has not occurred. When is invoked, a is created and returned but the results still have not been processed. Identity resolution, object materialization, and manipulation occur only when the user enumerates the results. ## Examples - The following example shows how to execute an asynchronous query by calling the method to start the query. The inline delegate calls the method to display the query results. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . + The following example shows how to execute an asynchronous query by calling the method to start the query. The inline delegate calls the method to display the query results. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetexecutequeryasync"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetexecutequeryasync"::: @@ -1285,9 +1285,9 @@ method is called to receive the results from the method. + The method is called to receive the results from the method. - The method does not complete until the response is received from the method. + The method does not complete until the response is received from the method. ]]> @@ -1353,7 +1353,7 @@ should be inspected to see the result of batch operations. Individual operation results can be retrieved on the operation objects returned by the enumerator. + The should be inspected to see the result of batch operations. Individual operation results can be retrieved on the operation objects returned by the enumerator. ]]> @@ -1429,7 +1429,7 @@ object contains the URI that, when executed, returns the next page of data in the query result. + The supplied object contains the URI that, when executed, returns the next page of data in the query result. ]]> @@ -1467,7 +1467,7 @@ method is used to query a data service by URI; the method causes an HTTP GET request to be issued to the data service. The request URI specified can be absolute or relative. + The method is used to query a data service by URI; the method causes an HTTP GET request to be issued to the data service. The request URI specified can be absolute or relative. If the `requestUri` is absolute, this method validates whether the URI points to the same data service that was specified when constructing the . If the `requestUri` is relative, this method strips off any leading slashes and appends `requestUri` to what was provided when constructing the . A slash is appended after the URI passed to the constructor, if one is not already present. @@ -1476,7 +1476,7 @@ ## Examples - This example uses a `do…while` loop to load `Customers` entities from a paged results from the data service. The method is called by using the next link URI to receive the next page of data. + This example uses a `do…while` loop to load `Customers` entities from a paged results from the data service. The method is called by using the next link URI to receive the next page of data. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetgetcustomerspaged"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetgetcustomerspaged"::: @@ -1526,14 +1526,14 @@ instances. Returns a that represents the response of the batch request as a whole. Individual query responses are represented as individual objects that can be accessed by enumerating the instance. + The queries are specified as instances. Returns a that represents the response of the batch request as a whole. Individual query responses are represented as individual objects that can be accessed by enumerating the instance. When this method returns the whole HTTP response for the batch request has been read from the network stream, but the responses have not been processed. No identity resolution or object materialization occurs for a specified entity in the response until it is enumerated. ## Examples - The following example shows how to call the method to execute an array of objects that contains queries that return both `Customers` and `Products` objects from the Northwind data service. The collection of objects in the returned is enumerated, and the collection of objects that is contained in each is also enumerated. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . + The following example shows how to call the method to execute an array of objects that contains queries that return both `Customers` and `Products` objects from the Northwind data service. The collection of objects in the returned is enumerated, and the collection of objects that is contained in each is also enumerated. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetbatchquery"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetbatchquery"::: @@ -1666,7 +1666,7 @@ method synchronously requests a data stream that contains the binary property of the requested `entity`. + The method synchronously requests a data stream that contains the binary property of the requested `entity`. In the AtomPub protocol, the `entity` is a Media Link Entry and the binary property is the associated Media Resource. @@ -1713,7 +1713,7 @@ method synchronously requests a data stream that contains the binary property of the requested `entity`. + The method synchronously requests a data stream that contains the binary property of the requested `entity`. In the AtomPub protocol, the `entity` is a Media Link Entry and the binary property is the associated Media Resource. @@ -1769,7 +1769,7 @@ ## Remarks The `acceptContentType` parameter should be a valid value for the Accept HTTP header. - The method synchronously requests a data stream that contains the binary property of the requested `entity`. + The method synchronously requests a data stream that contains the binary property of the requested `entity`. In the AtomPub protocol, the `entity` is a Media Link Entry and the binary property is the associated Media Resource. @@ -1821,7 +1821,7 @@ method returns a URI that is used to access the content of the Media Resource. + When the specified `entity` is a Media Link Entry, the method returns a URI that is used to access the content of the Media Resource. This URI is only used to in a GET request to read the content of a Media Resource. It may not respond to POST, PUT, or DELETE requests. @@ -2074,7 +2074,7 @@ ## Examples - This example returns related `Orders` entities with each `Customers` entity and uses a `do…while` loop to load `Customers` entities pages and a nested `while` loop to load pages of related `Orders` entities from the data service. The method is used to load pages of related `Orders` entities. + This example returns related `Orders` entities with each `Customers` entity and uses a `do…while` loop to load `Customers` entities pages and a nested `while` loop to load pages of related `Orders` entities from the data service. The method is used to load pages of related `Orders` entities. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetgetcustomerspagednested"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetgetcustomerspagednested"::: @@ -2289,7 +2289,7 @@ that contains status, headers, and errors that result from the call to . + A that contains status, headers, and errors that result from the call to . ]]> @@ -2347,15 +2347,15 @@ ## Remarks Operations are sent to the data service in the following order -1. +1. -2. +2. -3. +3. -4. +4. -5. and +5. and ]]> @@ -2390,7 +2390,7 @@ and then overridden as needed by calling one of the overloads. + This property is provided so that options such as merge and replace semantics can be set one time for the and then overridden as needed by calling one of the overloads. ]]> @@ -2455,7 +2455,7 @@ state. The adds this new link to the set of newly created links to be sent to the data service on the next call to . + A new link is created in the state. The adds this new link to the set of newly created links to be sent to the data service on the next call to . If the target argument is null, the link represented by sourceProperty should be removed or deleted (The link is moved to the state). @@ -2466,7 +2466,7 @@ ## Examples - The following example shows how to use the and methods to create links that define relationships. In this example, the navigation properties on the `Order_Details` object are also explicitly set. + The following example shows how to use the and methods to create links that define relationships. In this example, the navigation properties on the `Order_Details` object are also explicitly set. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddorderdetailtoorder"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddorderdetailtoorder"::: @@ -2527,13 +2527,13 @@ method sets the binary stream that is the Media Resource that is associated with the `entity`, which is called a Media Link Entry. + The method sets the binary stream that is the Media Resource that is associated with the `entity`, which is called a Media Link Entry. - Calling the method marks the entity as a Media Link Entry. The entity state is also set to so that the stream will be sent to the data service the next time that the method is called. + Calling the method marks the entity as a Media Link Entry. The entity state is also set to so that the stream will be sent to the data service the next time that the method is called. - The method reads the through to the end. A operation is not tried on the . + The method reads the through to the end. A operation is not tried on the . - When `closeStream` is `true`, the method closes the stream before it returns. The stream is closed even when an error occurs and the stream is not read. + When `closeStream` is `true`, the method closes the stream before it returns. The stream is closed even when an error occurs and the stream is not read. When the `entity` has the applied, the Media Resource cannot be a data stream. Remove this attribute before you try to set the data stream for the `entity`. @@ -2583,13 +2583,13 @@ method sets the binary stream that is the Media Resource that is associated with the `entity`, which is called a Media Link Entry. + The method sets the binary stream that is the Media Resource that is associated with the `entity`, which is called a Media Link Entry. - Calling the method marks the entity as Media Link Entry. The entity state is also set to so that the stream will be sent to the data service the next time that the method is called. + Calling the method marks the entity as Media Link Entry. The entity state is also set to so that the stream will be sent to the data service the next time that the method is called. - The method reads the through to the end. A operation is not tried on the . + The method reads the through to the end. A operation is not tried on the . - When `closeStream` is `true`, the method closes the stream before it returns. The stream is closed even when an error occurs and the stream is not read. + When `closeStream` is `true`, the method closes the stream before it returns. The stream is closed even when an error occurs and the stream is not read. When the `entity` has the applied, the Media Resource cannot be a data stream. Remove this attribute before you try to set the data stream for the `entity`. @@ -2781,7 +2781,7 @@ method on the to mark the item in the context as updated. An HTTP MERGE message is sent to the data service when is called. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . + The following example retrieves and modifies an existing object and then calls the method on the to mark the item in the context as updated. An HTTP MERGE message is sent to the data service when is called. This example uses the generated by the Add Service Reference tool based on the Northwind data service, which is created when you complete the WCF Data Services . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetmodifycustomer"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetmodifycustomer"::: @@ -2858,7 +2858,7 @@ ## Remarks Handling the event enables you to change the XML in a request before it is sent. - The event may occur on a different thread when you call without including in the supplied value. + The event may occur on a different thread when you call without including in the supplied value. ]]> diff --git a/xml/System.Data.Services.Client/DataServiceQuery.xml b/xml/System.Data.Services.Client/DataServiceQuery.xml index 0225edfeabf..ec512b8748f 100644 --- a/xml/System.Data.Services.Client/DataServiceQuery.xml +++ b/xml/System.Data.Services.Client/DataServiceQuery.xml @@ -25,11 +25,11 @@ An abstract class that represents a single query request to WCF Data Services. - or on the class. - + or on the class. + ]]> @@ -67,13 +67,13 @@ Asynchronously sends a request to execute the data service query. An object that is used to track the status of the asynchronous operation. - object is used to determine when the asynchronous operation has completed. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services). - - The method uses the same semantics as the method, however asynchronously sends the request so that the call does not block processing while waiting for the results from the service. According to the standard begin-end asynchronous pattern, the provided callback is invoked when query results are retrieved. - + object is used to determine when the asynchronous operation has completed. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services). + + The method uses the same semantics as the method, however asynchronously sends the request so that the call does not block processing while waiting for the results from the service. According to the standard begin-end asynchronous pattern, the provided callback is invoked when query results are retrieved. + ]]> @@ -140,13 +140,13 @@ Executes the query against the data service. An that contains the results of the query operation. - method is used to execute the given data service query. - - The method generates an HTTP GET request that is set to the data service. - + method is used to execute the given data service query. + + The method generates an HTTP GET request that is set to the data service. + ]]> When the data service returns an HTTP 404: Resource Not Found error. @@ -226,11 +226,11 @@ Gets the object that can be used to iterate through the collection returned by the query. An enumerator over the query results. - diff --git a/xml/System.Data.Services.Client/DataServiceQueryException.xml b/xml/System.Data.Services.Client/DataServiceQueryException.xml index b52efc530b0..1e4b81a60f1 100644 --- a/xml/System.Data.Services.Client/DataServiceQueryException.xml +++ b/xml/System.Data.Services.Client/DataServiceQueryException.xml @@ -31,7 +31,7 @@ to get the exception results. + The caller should inspect to get the exception results. ]]> @@ -72,8 +72,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -113,8 +113,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -188,8 +188,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Data.Services.Client/DataServiceQuery`1.xml b/xml/System.Data.Services.Client/DataServiceQuery`1.xml index ac470a9f5cf..da5ac5c23c0 100644 --- a/xml/System.Data.Services.Client/DataServiceQuery`1.xml +++ b/xml/System.Data.Services.Client/DataServiceQuery`1.xml @@ -42,7 +42,7 @@ or on the class. + No public constructors are defined on this class. Object instances are created by using or on the class. ]]> @@ -84,12 +84,12 @@ ## Examples - The following example shows a that is used with sequential method calls to only return orders with a freight cost of more than $30 and to order the results by the ship date in descending order. + The following example shows a that is used with sequential method calls to only return orders with a freight cost of more than $30 and to order the results by the ship date in descending order. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddqueryoptions"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptions"::: - The following example shows how to compose a LINQ query that is equivalent to the previous query that used . + The following example shows how to compose a LINQ query that is equivalent to the previous query that used . :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddqueryoptionslinq"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptionslinq"::: @@ -152,7 +152,7 @@ or . + Gets the type represented by T in the generic methods: or . ]]> @@ -300,7 +300,7 @@ method is called, the is executed against the service. + When the method is called, the is executed against the service. ]]> @@ -330,12 +330,12 @@ method is equivalent to including the `$inlinecount` query option in the query URI. + Calling the method is equivalent to including the `$inlinecount` query option in the query URI. ## Examples - This example executes a query after it calls the method. The property is used to determine number of entities returned by the query. + This example executes a query after it calls the method. The property is used to determine number of entities returned by the query. :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetcountallcustomers"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetcountallcustomers"::: @@ -430,9 +430,9 @@ method is called, the is executed against the service. + When the method is called, the is executed against the service. - returns an enumerable the first time it is called. On successive calls it returns null. + returns an enumerable the first time it is called. On successive calls it returns null. ]]> diff --git a/xml/System.Data.Services.Client/DataServiceRequestArgs.xml b/xml/System.Data.Services.Client/DataServiceRequestArgs.xml index d44bf6b64a7..37c45834761 100644 --- a/xml/System.Data.Services.Client/DataServiceRequestArgs.xml +++ b/xml/System.Data.Services.Client/DataServiceRequestArgs.xml @@ -145,7 +145,7 @@ object that contains key-value pairs of strings for each header in the request. + The response is a object that contains key-value pairs of strings for each header in the request. No validation is performed on the headers in the property. Therefore, make sure that you do not change an HTTP header in a way that changes the meaning of the request. diff --git a/xml/System.Data.Services.Client/DataServiceRequestException.xml b/xml/System.Data.Services.Client/DataServiceRequestException.xml index 6d98a9368ba..0502f8fe7cf 100644 --- a/xml/System.Data.Services.Client/DataServiceRequestException.xml +++ b/xml/System.Data.Services.Client/DataServiceRequestException.xml @@ -65,8 +65,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -106,8 +106,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -181,8 +181,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Data.Services.Client/DataServiceRequest`1.xml b/xml/System.Data.Services.Client/DataServiceRequest`1.xml index 7d5641d3f9a..03486e8753d 100644 --- a/xml/System.Data.Services.Client/DataServiceRequest`1.xml +++ b/xml/System.Data.Services.Client/DataServiceRequest`1.xml @@ -22,107 +22,107 @@ To be added. Represents request objects submitted as a batch to the data service. - instances. A is returned that represents the response of the batch request as a whole. Individual query responses are represented as objects, derived from , that are accessible by enumerating the instance. - - - -## Examples - When returns, the entire HTTP response for the batch request has been read from the network stream, but the responses have not been processed. Identity resolution and object materialization do not occur for a specified entity in the response until it is iterated as shown in the following example. - + instances. A is returned that represents the response of the batch request as a whole. Individual query responses are represented as objects, derived from , that are accessible by enumerating the instance. + + + +## Examples + When returns, the entire HTTP response for the batch request has been read from the network stream, but the responses have not been processed. Identity resolution and object materialization do not occur for a specified entity in the response until it is iterated as shown in the following example. + ```csharp -DataServiceContext service = new DataServiceContext(new - Uri("http://myserviceroot")); - -// Create query batches. -DataServiceRequest[] reqs = new DataServiceRequest[] { - new DataServiceRequest( - new Uri("http://myserviceroot/Categories")), - new DataServiceRequest( - new Uri("http://myserviceroot/Customers")) -}; - -DataServiceResponse dsr; -try -{ - // Client will not throw an exception on ExecuteBatch because the - // entire response has not been processed yet to know - // whether an exception should be thrown. - - dsr = service.ExecuteBatch(reqs); - - if (dsr.IsBatchResponse) - { - /*inspect HTTP artifacts associated with the entire batch: - dsr.BatchHeaders, dsr.BatchStatusCode*/ } - - foreach (QueryOperationResponse qr in dsr) - { - if (IsErrorStatusCode(qr.StatusCode)) - { - //q.Error.Message contains the full contents of the error. - /* process any part of the Error Contract ( element) - sent from the service. */ - } - } - else - { - if (qr.Query.ElementType == typeof(Customer)) - { - //process customers - foreach (Customer c in qr){ /*process the customer*/ } - - // the DataServiceContext does not materialize, resolve - // identity on Customer until it is enumerated. - } - else if (qr.Query.ElementType == typeof(Category)) - { - // Process categories. - foreach (Category cat in qr) - { - /*process the category*/ - } - // the DataServiceContext does not materialize or - // resolve identity on the Category until - // it is enumerated. - // This means that instream errors will be thrown - // during iteration. - } - } - } -} -catch (DataServiceRequestException e) -{ - // This error is thrown if the data service returns with - // a response code < 200 or >299 or the top level element. - // If neither of the above or true, this exception is not - // thrown. - - dsr = e.Response; - - if (dsr.IsBatchResponse) - { - /*inspect HTTP artifacts associated with the entire batch: - dsr.BatchHeaders, dsr.BatchStatusCode*/ - } - - /* There will always only be one of these because if the top level - status code was >=200 and =<299 and the first element was not an - error, the call to start the query will not throw. */ - - foreach (QueryOperationResponse qr in dsr) - { - if (qr.Error != null) - { - // Process error. - } - } -} - -``` - +DataServiceContext service = new DataServiceContext(new + Uri("http://myserviceroot")); + +// Create query batches. +DataServiceRequest[] reqs = new DataServiceRequest[] { + new DataServiceRequest( + new Uri("http://myserviceroot/Categories")), + new DataServiceRequest( + new Uri("http://myserviceroot/Customers")) +}; + +DataServiceResponse dsr; +try +{ + // Client will not throw an exception on ExecuteBatch because the + // entire response has not been processed yet to know + // whether an exception should be thrown. + + dsr = service.ExecuteBatch(reqs); + + if (dsr.IsBatchResponse) + { + /*inspect HTTP artifacts associated with the entire batch: + dsr.BatchHeaders, dsr.BatchStatusCode*/ } + + foreach (QueryOperationResponse qr in dsr) + { + if (IsErrorStatusCode(qr.StatusCode)) + { + //q.Error.Message contains the full contents of the error. + /* process any part of the Error Contract ( element) + sent from the service. */ + } + } + else + { + if (qr.Query.ElementType == typeof(Customer)) + { + //process customers + foreach (Customer c in qr){ /*process the customer*/ } + + // the DataServiceContext does not materialize, resolve + // identity on Customer until it is enumerated. + } + else if (qr.Query.ElementType == typeof(Category)) + { + // Process categories. + foreach (Category cat in qr) + { + /*process the category*/ + } + // the DataServiceContext does not materialize or + // resolve identity on the Category until + // it is enumerated. + // This means that instream errors will be thrown + // during iteration. + } + } + } +} +catch (DataServiceRequestException e) +{ + // This error is thrown if the data service returns with + // a response code < 200 or >299 or the top level element. + // If neither of the above or true, this exception is not + // thrown. + + dsr = e.Response; + + if (dsr.IsBatchResponse) + { + /*inspect HTTP artifacts associated with the entire batch: + dsr.BatchHeaders, dsr.BatchStatusCode*/ + } + + /* There will always only be one of these because if the top level + status code was >=200 and =<299 and the first element was not an + error, the call to start the query will not throw. */ + + foreach (QueryOperationResponse qr in dsr) + { + if (qr.Error != null) + { + // Process error. + } + } +} + +``` + ]]> diff --git a/xml/System.Data.Services.Client/DataServiceStreamResponse.xml b/xml/System.Data.Services.Client/DataServiceStreamResponse.xml index d17d9c57af6..566b3d09202 100644 --- a/xml/System.Data.Services.Client/DataServiceStreamResponse.xml +++ b/xml/System.Data.Services.Client/DataServiceStreamResponse.xml @@ -108,11 +108,11 @@ method when you have finished using the . This releases resources held by the object. You should always do this to release the resources held by the ; otherwise, the consumed resources will not be released until after the garbage collector calls the method on the object. + Call the method when you have finished using the . This releases resources held by the object. You should always do this to release the resources held by the ; otherwise, the consumed resources will not be released until after the garbage collector calls the method on the object. - After the method is called and all references to the are released, the memory used can be reclaimed by garbage collection. + After the method is called and all references to the are released, the memory used can be reclaimed by garbage collection. - You cannot use after calling the method. + You cannot use after calling the method. ]]> @@ -141,7 +141,7 @@ object that contains key-value pairs of strings for each header in the response. + The response is a object that contains key-value pairs of strings for each header in the response. ]]> @@ -174,9 +174,9 @@ The returned is read-only. - You must call either the method on the or the method on the . Otherwise, the network connection remains open and unavailable to other applications. + You must call either the method on the or the method on the . Otherwise, the network connection remains open and unavailable to other applications. - The method is used to access the stream. + The method is used to access the stream. ]]> diff --git a/xml/System.Data.Services.Client/EntityChangedParams.xml b/xml/System.Data.Services.Client/EntityChangedParams.xml index 0f627382de6..4646d11182c 100644 --- a/xml/System.Data.Services.Client/EntityChangedParams.xml +++ b/xml/System.Data.Services.Client/EntityChangedParams.xml @@ -18,19 +18,19 @@ Encapsulates the arguments of a delegate. - with custom methods that are called when changes occur to data that is bound to the binding collection. When the event occurs, the supplied method prevents an item that has been removed from the binding collection from being deleted from the data service. When the event occurs, the `ShipDate` value is validated to ensure that changes are not made to orders that have already shipped. - + with custom methods that are called when changes occur to data that is bound to the binding collection. When the event occurs, the supplied method prevents an item that has been removed from the binding collection from being deleted from the data service. When the event occurs, the `ShipDate` value is validated to ensure that changes are not made to orders that have already shipped. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml.cs" id="Snippetwpfdatabindingcustom"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml.vb" id="Snippetwpfdatabindingcustom"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom2.xaml.vb" id="Snippetwpfdatabindingcustom"::: - - The following XAML code defines the window for the previous example. - - :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml" id="Snippetwpfdatabindingcustomxaml"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom2.xaml.vb" id="Snippetwpfdatabindingcustom"::: + + The following XAML code defines the window for the previous example. + + :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml" id="Snippetwpfdatabindingcustomxaml"::: + ]]> Binding Data to Controls (WCF Data Services) diff --git a/xml/System.Data.Services.Client/EntityCollectionChangedParams.xml b/xml/System.Data.Services.Client/EntityCollectionChangedParams.xml index f36d7446278..72677e374c4 100644 --- a/xml/System.Data.Services.Client/EntityCollectionChangedParams.xml +++ b/xml/System.Data.Services.Client/EntityCollectionChangedParams.xml @@ -18,19 +18,19 @@ Encapsulates the arguments of a delegate. - with custom methods that are called when changes occur to data that is bound to the binding collection. When the event occurs, the supplied method prevents an item that has been removed from the binding collection from being deleted from the data service. When the event occurs, the `ShipDate` value is validated to ensure that changes are not made to orders that have already shipped. - + with custom methods that are called when changes occur to data that is bound to the binding collection. When the event occurs, the supplied method prevents an item that has been removed from the binding collection from being deleted from the data service. When the event occurs, the `ShipDate` value is validated to ensure that changes are not made to orders that have already shipped. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml.cs" id="Snippetwpfdatabindingcustom"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml.vb" id="Snippetwpfdatabindingcustom"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom2.xaml.vb" id="Snippetwpfdatabindingcustom"::: - - The following XAML code defines the window for the previous example. - - :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml" id="Snippetwpfdatabindingcustomxaml"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom2.xaml.vb" id="Snippetwpfdatabindingcustom"::: + + The following XAML code defines the window for the previous example. + + :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderscustom.xaml" id="Snippetwpfdatabindingcustomxaml"::: + ]]> Binding Data to Controls (WCF Data Services) @@ -63,11 +63,11 @@ A value that indicates how the collection was changed. A value that indicates how the collection was changed. - and are supported. - + and are supported. + ]]> diff --git a/xml/System.Data.Services.Client/EntityDescriptor.xml b/xml/System.Data.Services.Client/EntityDescriptor.xml index 8b5412d141b..7bf50ecba63 100644 --- a/xml/System.Data.Services.Client/EntityDescriptor.xml +++ b/xml/System.Data.Services.Client/EntityDescriptor.xml @@ -27,11 +27,11 @@ method returns a object that contains a series of objects each of which contains a sequence of or instances that represent changes that were persisted. + The method returns a object that contains a series of objects each of which contains a sequence of or instances that represent changes that were persisted. For successful operations, the property of the descriptor will be set to unchanged and the new values for insert and update operations will be merged according to the merge settings. - For operations with errors, the of the descriptor will remain the same as it was before was called. + For operations with errors, the of the descriptor will remain the same as it was before was called. If an error occurred and processing stopped during an operation, the will remain unchanged. @@ -364,7 +364,7 @@ property returns an eTag value that indicates the state of the Media Resource targeted for update since the last call to when the entity is a media link entry. + The property returns an eTag value that indicates the state of the Media Resource targeted for update since the last call to when the entity is a media link entry. The eTag associated with the media resource is used to represent original values for use with optimistic concurrency checks according to eTag rules in HTTP [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=114956). diff --git a/xml/System.Data.Services.Client/LinkDescriptor.xml b/xml/System.Data.Services.Client/LinkDescriptor.xml index 3e898f5aaf9..a3e5d5b2067 100644 --- a/xml/System.Data.Services.Client/LinkDescriptor.xml +++ b/xml/System.Data.Services.Client/LinkDescriptor.xml @@ -24,17 +24,17 @@ Provides a description of modifications done to entities by operations returned in a . - method returns a object that contains a series of objects, each of which contains a sequence of or instances that represent persisted changes. - - For successful operations, the property of the descriptor is set to unchanged and the new values for insert and update operations are merged according to the merge settings. - - For operations with errors, the of the descriptor will remain the same as they were before was called. - - If an error occurred and processing stopped during an operation, the will remain unchanged. - + method returns a object that contains a series of objects, each of which contains a sequence of or instances that represent persisted changes. + + For successful operations, the property of the descriptor is set to unchanged and the new values for insert and update operations are merged according to the merge settings. + + For operations with errors, the of the descriptor will remain the same as they were before was called. + + If an error occurred and processing stopped during an operation, the will remain unchanged. + ]]> diff --git a/xml/System.Data.Services.Client/MediaEntryAttribute.xml b/xml/System.Data.Services.Client/MediaEntryAttribute.xml index 948795c9b2e..340c9a2565b 100644 --- a/xml/System.Data.Services.Client/MediaEntryAttribute.xml +++ b/xml/System.Data.Services.Client/MediaEntryAttribute.xml @@ -29,7 +29,7 @@ ## Remarks The class is treated as a media link entry, which is an AtomPub protocol for handling binary data and metadata about that binary data. - A type marked with this attribute has altered behavior when is called. The media property is also called a Media resource. On saving, the media property of the type denoted by the property, is inserted by a POST request to the URI `//$value`. + A type marked with this attribute has altered behavior when is called. The media property is also called a Media resource. On saving, the media property of the type denoted by the property, is inserted by a POST request to the URI `//$value`. After the `POST`, a `PUT` request with all the properties on the type other than the property, which is binary content, are sent to the URI `/()`. diff --git a/xml/System.Data.Services.Client/MimeTypePropertyAttribute.xml b/xml/System.Data.Services.Client/MimeTypePropertyAttribute.xml index 0233712ab13..c6c11cfc915 100644 --- a/xml/System.Data.Services.Client/MimeTypePropertyAttribute.xml +++ b/xml/System.Data.Services.Client/MimeTypePropertyAttribute.xml @@ -24,13 +24,13 @@ Annotates a property on a class that has been annotated with the . - . The property specified is automatically set to the mime type of data when a media resource associated with the media link entry is delay-loaded by the method. - - The system also reads the mime type from this property and uses it to set the `Content-Type` header in a POST request for a media link entry. A media link entry is an AtomPub protocol construct for handling binary data and metadata. - + . The property specified is automatically set to the mime type of data when a media resource associated with the media link entry is delay-loaded by the method. + + The system also reads the mime type from this property and uses it to set the `Content-Type` header in a POST request for a media link entry. A media link entry is an AtomPub protocol construct for handling binary data and metadata. + ]]> diff --git a/xml/System.Data.Services.Client/QueryOperationResponse.xml b/xml/System.Data.Services.Client/QueryOperationResponse.xml index 6cac65a204f..1bbc092b866 100644 --- a/xml/System.Data.Services.Client/QueryOperationResponse.xml +++ b/xml/System.Data.Services.Client/QueryOperationResponse.xml @@ -81,13 +81,13 @@ Gets a object containing the URI that is used to retrieve the next page of related entities in the specified collection. A continuation object that points to the next page for the collection. - method is used to obtain the URI that is used to retrieve the next results page for a nested result. - - Specify a `null` value for `collection` when the collection is the top-level collection. - + method is used to obtain the URI that is used to retrieve the next results page for a nested result. + + Specify a `null` value for `collection` when the collection is the top-level collection. + ]]> @@ -196,11 +196,11 @@ Gets the server result set count value from a query, if the query has requested the value. Zero or a positive value equal to the number of entities in the set on the server. - is raised when count was not part of the original request, that is, if the count tag is not found in the response stream. - + is raised when count was not part of the original request, that is, if the count tag is not found in the response stream. + ]]> The count tag is not found in the response stream. diff --git a/xml/System.Data.Services.Client/QueryOperationResponse`1.xml b/xml/System.Data.Services.Client/QueryOperationResponse`1.xml index c5492e65292..c81975bdc85 100644 --- a/xml/System.Data.Services.Client/QueryOperationResponse`1.xml +++ b/xml/System.Data.Services.Client/QueryOperationResponse`1.xml @@ -52,14 +52,14 @@ Gets a object that contains the URI that is used to retrieve the next results page. An object that contains the URI that is used to return the next results page. - method in a `do…while` loop to load `Customers` entities from a paged results from the data service. - + method in a `do…while` loop to load `Customers` entities from a paged results from the data service. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetgetcustomerspaged"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetgetcustomerspaged"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetgetcustomerspaged"::: + ]]> @@ -110,11 +110,11 @@ The server result set count value from a query, if the query has requested the value. The return value can be either zero or a positive value equal to the number of entities in the set on the server. - is thrown when the count was not part of the original request; that is, if the count tag is not found in the response stream. - + is thrown when the count was not part of the original request; that is, if the count tag is not found in the response stream. + ]]> diff --git a/xml/System.Data.Services.Client/TrackingMode.xml b/xml/System.Data.Services.Client/TrackingMode.xml index b231ec6fb80..f6179878667 100644 --- a/xml/System.Data.Services.Client/TrackingMode.xml +++ b/xml/System.Data.Services.Client/TrackingMode.xml @@ -17,13 +17,13 @@ Determines whether changes that are made to a are tracked. - enumeration specifies whether or not changes that are made to items in the collection are tracked automatically. - - Values from the enumeration are used when you create a new instance of the class. - + enumeration specifies whether or not changes that are made to items in the collection are tracked automatically. + + Values from the enumeration are used when you create a new instance of the class. + ]]> Binding Data to Controls (ADO.NET Data Services) diff --git a/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml b/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml index 689265aa0d3..6faee816dce 100644 --- a/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml +++ b/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml @@ -150,7 +150,7 @@ is `true`, the feed is backward compatible with WCF Data Services client applications that use protocol version 1.0. When the value of is `false`, the protocol version used by the data service must be 2.0 or later versions. For more information, see [Data Service Versioning](/dotnet/framework/data/wcf/data-service-versioning-wcf-data-services). + When the value of is `true`, the feed is backward compatible with WCF Data Services client applications that use protocol version 1.0. When the value of is `false`, the protocol version used by the data service must be 2.0 or later versions. For more information, see [Data Service Versioning](/dotnet/framework/data/wcf/data-service-versioning-wcf-data-services). ]]> @@ -226,7 +226,7 @@ nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. + If neither nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. ]]> @@ -263,7 +263,7 @@ ## Remarks If mapping to non-syndication element/attribute, this property is the namespace for the target element/attribute. - If neither nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. + If neither nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. ]]> @@ -298,11 +298,11 @@ property is set, the and properties must also be set. + When the property is set, the and properties must also be set. - The value of must be `null` (`Nothing` in Visual Basic) when the value of the property is anything other than . + The value of must be `null` (`Nothing` in Visual Basic) when the value of the property is anything other than . - must be a path expression in which nested elements are separated by a backslash (`/`) and attributes are specified by an ampersand (`@`). In the following example, the string `UnitsInStock/@ReorderLevel` maps a property value to an attribute named `ReorderLevel` on a child element named `UnitsInStock` of the root entry element. + must be a path expression in which nested elements are separated by a backslash (`/`) and attributes are specified by an ampersand (`@`). In the following example, the string `UnitsInStock/@ReorderLevel` maps a property value to an attribute named `ReorderLevel` on a child element named `UnitsInStock` of the root entry element. :::code language="xml" source="~/snippets/xml/VS_Snippets_Misc/astoria_custom_feeds/xml/northwind.csdl" id="Snippetedmfeedmappedtoattributespecific"::: @@ -345,7 +345,7 @@ ## Remarks If mapping to syndication element, this property is the name of the syndication item. - This value must be set to `None` if the is not null. + This value must be set to `None` if the is not null. ]]> @@ -382,7 +382,7 @@ ## Remarks If mapping to syndication content, this property is the content type of syndication item. - When you specify a value of for the attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. + When you specify a value of for the attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. ]]> diff --git a/xml/System.Data.Services.Common/SyndicationTextContentKind.xml b/xml/System.Data.Services.Common/SyndicationTextContentKind.xml index 733555d1807..2b8e925463b 100644 --- a/xml/System.Data.Services.Common/SyndicationTextContentKind.xml +++ b/xml/System.Data.Services.Common/SyndicationTextContentKind.xml @@ -17,11 +17,11 @@ Enumeration used to identify text content of syndication item. - attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. - + attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. + ]]> diff --git a/xml/System.Data.Services.Providers/IDataServiceMetadataProvider.xml b/xml/System.Data.Services.Providers/IDataServiceMetadataProvider.xml index 0a227fc0c1d..ad54be5e9fd 100644 --- a/xml/System.Data.Services.Providers/IDataServiceMetadataProvider.xml +++ b/xml/System.Data.Services.Providers/IDataServiceMetadataProvider.xml @@ -84,15 +84,15 @@ Attempts to return all types that derive from the specified resource type. An collection of derived objects. - method must return a collection of all the types derived from `resourceType`. - - The type passed to the method by using the `resourceType` parameter must not be returned in the collection. - - An implementer of the interface must return a null value when no types are derived from the supplied type. - + method must return a collection of all the types derived from `resourceType`. + + The type passed to the method by using the `resourceType` parameter must not be returned in the collection. + + An implementer of the interface must return a null value when no types are derived from the supplied type. + ]]> diff --git a/xml/System.Data.Services.Providers/IDataServicePagingProvider.xml b/xml/System.Data.Services.Providers/IDataServicePagingProvider.xml index 3d83305f7c1..e2ae91b291b 100644 --- a/xml/System.Data.Services.Providers/IDataServicePagingProvider.xml +++ b/xml/System.Data.Services.Providers/IDataServicePagingProvider.xml @@ -40,11 +40,11 @@ Returns the next-page token to put in the query option. The next-page token as a collection of primitive types. - @@ -76,11 +76,11 @@ Continuation token parsed into primitive type values. Gets the next-page token from the query option in the request URI. - method gets the next-page token from the `$skiptoken` in the request URI, parsed into primitive values, for the provider. - + method gets the next-page token from the `$skiptoken` in the request URI, parsed into primitive values, for the provider. + ]]> diff --git a/xml/System.Data.Services.Providers/IDataServiceStreamProvider.xml b/xml/System.Data.Services.Providers/IDataServiceStreamProvider.xml index 605ec7f97b7..3ae4e4eceff 100644 --- a/xml/System.Data.Services.Providers/IDataServiceStreamProvider.xml +++ b/xml/System.Data.Services.Providers/IDataServiceStreamProvider.xml @@ -57,7 +57,7 @@ method provides the implementation to delete a media resource when its associated media link entry is deleted from the data service. For more information, see [Streaming Provider](/dotnet/framework/data/wcf/streaming-provider-wcf-data-services). + The method provides the implementation to delete a media resource when its associated media link entry is deleted from the data service. For more information, see [Streaming Provider](/dotnet/framework/data/wcf/streaming-provider-wcf-data-services). ]]> @@ -107,7 +107,7 @@ - `null` - when an If-Match or If-None-Match header is not present in the request. - The method is called by the data service runtime to acquire the stream that the data service returns to the client when the client requests the media resource for the specified `entity`, which is a media link entry. For more information, see [Streaming Provider](/dotnet/framework/data/wcf/streaming-provider-wcf-data-services). + The method is called by the data service runtime to acquire the stream that the data service returns to the client when the client requests the media resource for the specified `entity`, which is a media link entry. For more information, see [Streaming Provider](/dotnet/framework/data/wcf/streaming-provider-wcf-data-services). ]]> @@ -142,9 +142,9 @@ method is called by the data service runtime to obtain the URI that clients should use when they make retrieve (that is, GET) requests for the media resource. + The method is called by the data service runtime to obtain the URI that clients should use when they make retrieve (that is, GET) requests for the media resource. - The value returned by the method implementation is used as the edit-media link in the media link entry to references the location of the media resource. + The value returned by the method implementation is used as the edit-media link in the media link entry to references the location of the media resource. When the method implementation returns null, the data service will construct a default , which is usually the URI of the entity appended with `/$value`. @@ -181,7 +181,7 @@ method is called by the data service runtime to retrieve the Content-Type of the media resource that belongs to the specified `entity`. Use the method implementation to set the Content-Type of the media resource. Do not directly set the Content-Type header in your provider implementation. + The method is called by the data service runtime to retrieve the Content-Type of the media resource that belongs to the specified `entity`. Use the method implementation to set the Content-Type of the media resource. Do not directly set the Content-Type header in your provider implementation. ]]> @@ -216,9 +216,9 @@ method is called by the data service runtime to retrieve the eTag of the media resource that is associated with the `entity`. + The method is called by the data service runtime to retrieve the eTag of the media resource that is associated with the `entity`. - You must implement the method to enable the data service to manage concurrency for the media resource. + You must implement the method to enable the data service to manage concurrency for the media resource. ]]> @@ -257,9 +257,9 @@ method is called by the data service runtime when an insert or update operation is being processed for the media resource that is associated with the `entity`. + The method is called by the data service runtime when an insert or update operation is being processed for the media resource that is associated with the `entity`. - The method should never return a `null` value. + The method should never return a `null` value. The `operationContext` is supplied as an argument because an implementer of this interface method will need information from the HTTP request headers to create a write stream. When you implement this method, you must perform concurrency checks as needed. If an If-Match or If-None-Match request header was included in the request, the `etag` will not be `null`. In this case, this method must perform the appropriate concurrency check. If the concurrency check passes, this method should return the requested stream. If the concurrency checks fail, the method should raise a with the appropriate HTTP response code. @@ -279,7 +279,7 @@ The data service runtime closes the stream when all bytes have been successfully written to the stream. If an error occurs while writing to the stream, the data service generates an error response to the client. - When you implement the method, you should raise the following exceptions as indicated: + When you implement the method, you should raise the following exceptions as indicated: |Exception type|Condition| |--------------------|---------------| @@ -320,9 +320,9 @@ method is called by the data service when a new entity that is a media link entry is being created together with its media resource. An implementer of this method must inspect the request headers in `operationContext` and return the namespace qualified type name that represents the type that the data service runtime must instantiate to create the media link entry that is associated with the new media resource. The string that represents this type name is passed to the method to create the media link entry. + The method is called by the data service when a new entity that is a media link entry is being created together with its media resource. An implementer of this method must inspect the request headers in `operationContext` and return the namespace qualified type name that represents the type that the data service runtime must instantiate to create the media link entry that is associated with the new media resource. The string that represents this type name is passed to the method to create the media link entry. - When you implement the method, you should raise the following exceptions as indicated: + When you implement the method, you should raise the following exceptions as indicated: |Exception type|Condition| |--------------------|---------------| diff --git a/xml/System.Data.Services.Providers/OpenTypeMethods.xml b/xml/System.Data.Services.Providers/OpenTypeMethods.xml index 300b1097d54..2b92f67b1af 100644 --- a/xml/System.Data.Services.Providers/OpenTypeMethods.xml +++ b/xml/System.Data.Services.Providers/OpenTypeMethods.xml @@ -17,11 +17,11 @@ Used to perform late-bound operations on open properties. - Data Services Providers (WCF Data Services) @@ -53,11 +53,11 @@ Adds two values. The result of the arithmetic operation. - method adds two values without overflow checking. - + method adds two values without overflow checking. + ]]> @@ -170,11 +170,11 @@ Converts a value to the specified type. The converted value. - method is used to perform a type cast on the specified `value`. - + method is used to perform a type cast on the specified `value`. + ]]> @@ -260,11 +260,11 @@ if ends with ; otherwise, . - @@ -462,11 +462,11 @@ Returns the index of a substring in the target string. The index of the location of in the . - method returns a null value when `substring` cannot be found in `targetString`. - + method returns a null value when `substring` cannot be found in `targetString`. + ]]> @@ -495,11 +495,11 @@ Gets the number of characters in the supplied string object. The length of the string value. - . - + . + ]]> @@ -668,11 +668,11 @@ Multiplies two values. The product of the two values. - method multiplies two values without overflow checking. - + method multiplies two values without overflow checking. + ]]> @@ -932,11 +932,11 @@ Returns the substring after the specified starting index location. The substring. - method returns all characters from `startIndex` through the end of the `targetString`. - + method returns all characters from `startIndex` through the end of the `targetString`. + ]]> @@ -969,11 +969,11 @@ Returns the substring of a specific length after the specified starting index location. The substring. - method returns the `length` number of characters from `startIndex` through the end of the `targetString`. - + method returns the `length` number of characters from `startIndex` through the end of the `targetString`. + ]]> diff --git a/xml/System.Data.Services.Providers/ResourceProperty.xml b/xml/System.Data.Services.Providers/ResourceProperty.xml index 0bdfd5e3de3..355aa84e371 100644 --- a/xml/System.Data.Services.Providers/ResourceProperty.xml +++ b/xml/System.Data.Services.Providers/ResourceProperty.xml @@ -36,7 +36,7 @@ 4. U+212E '℮' - If your property names can contain these characters, make sure that they are escaped properly in your provider implementation. The method will not properly escape these invalid EDM characters." + If your property names can contain these characters, make sure that they are escaped properly in your provider implementation. The method will not properly escape these invalid EDM characters." ]]> @@ -80,7 +80,7 @@ 4. U+212E '℮' - If your property names can contain these characters, make sure that they are escaped properly in your provider implementation. The method will not properly escape these invalid EDM characters." + If your property names can contain these characters, make sure that they are escaped properly in your provider implementation. The method will not properly escape these invalid EDM characters." ]]> @@ -116,7 +116,7 @@ property returns `true`, the data service runtime uses reflection to get the property information on the declaring. of the . + When the property returns `true`, the data service runtime uses reflection to get the property information on the declaring. of the . When the property returns `false`, the data service runtime uses the interface to get or set this property value. diff --git a/xml/System.Data.Services.Providers/ResourceType.xml b/xml/System.Data.Services.Providers/ResourceType.xml index 217e0c46e33..ceb42953011 100644 --- a/xml/System.Data.Services.Providers/ResourceType.xml +++ b/xml/System.Data.Services.Providers/ResourceType.xml @@ -23,11 +23,11 @@ Represents a data service primitive, complex, or entity type. - @@ -491,11 +491,11 @@ Returns a list of properties declared by this resource type. The list of properties declared on this type. - method enables you to defer loading of the properties of a resource type. This method is called only one time when either or properties are accessed. - + method enables you to defer loading of the properties of a resource type. This method is called only one time when either or properties are accessed. + ]]> diff --git a/xml/System.Data.Services/DataServiceConfiguration.xml b/xml/System.Data.Services/DataServiceConfiguration.xml index 3e2e8fdd6e2..d3ab53b9d36 100644 --- a/xml/System.Data.Services/DataServiceConfiguration.xml +++ b/xml/System.Data.Services/DataServiceConfiguration.xml @@ -89,17 +89,17 @@ method is used to register a type with the data service runtime. After registration, a type can be returned in the properties of an open type. This makes the type visible in `$metadata` output and usable by the data service. + The method is used to register a type with the data service runtime. After registration, a type can be returned in the properties of an open type. This makes the type visible in `$metadata` output and usable by the data service. - The supplied `typeName` must be defined in the same format as a type in the data model and not as a CLR type. The registered types are added to those types already made available by calling the method. + The supplied `typeName` must be defined in the same format as a type in the data model and not as a CLR type. The registered types are added to those types already made available by calling the method. The data service runtime cannot determine what kind of data type the `typeName` maps to until information about the type can be obtained from the underlying provider. A value of '*' can be supplied for `typeName`, which matches all types. - When the data service runtime enumerates types or must obtain a type from the underlying data provider, it must first determine whether the type must be visible when the method is called. When the type is not available in this manner, then types registered by using the method are checked. When a type is not made visible by using either of these mechanisms, that type is not included in the response to a `$metadata` request, and instances of that type are not returned to the client as the response of a request to the data service. + When the data service runtime enumerates types or must obtain a type from the underlying data provider, it must first determine whether the type must be visible when the method is called. When the type is not available in this manner, then types registered by using the method are checked. When a type is not made visible by using either of these mechanisms, that type is not included in the response to a `$metadata` request, and instances of that type are not returned to the client as the response of a request to the data service. - The method can be called many times with the same type name. + The method can be called many times with the same type name. ]]> @@ -362,7 +362,7 @@ method to register a type when it cannot be detected by the runtime by using the default set of rules. + A provider can use the method to register a type when it cannot be detected by the runtime by using the default set of rules. ]]> @@ -520,7 +520,7 @@ property sets the default verbose error behavior for the whole service. Individual responses can behave differently depending on the value of the property of the arguments to the method on the class. + The property sets the default verbose error behavior for the whole service. Individual responses can behave differently depending on the value of the property of the arguments to the method on the class. For security reasons, verbose errors should only be enabled during development, not in production environments, diff --git a/xml/System.Data.Services/DataServiceException.xml b/xml/System.Data.Services/DataServiceException.xml index be4cc423937..672afec451f 100644 --- a/xml/System.Data.Services/DataServiceException.xml +++ b/xml/System.Data.Services/DataServiceException.xml @@ -97,8 +97,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -196,8 +196,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> diff --git a/xml/System.Data.Services/DataService`1.xml b/xml/System.Data.Services/DataService`1.xml index 2b3088261bf..643ee326c40 100644 --- a/xml/System.Data.Services/DataService`1.xml +++ b/xml/System.Data.Services/DataService`1.xml @@ -35,13 +35,13 @@ Type that defines the data service. The main entry point for developing an ADO.NET Data Service. - class does the basic integration of all components of the server system. A new data service that uses system defaults for authorization and caching is created by defining a class that derives from the class and by referencing a compatible data model. - - The type of the must expose at least one property that returns an entity set that is an collection of entity types. This class must also implement the interface to enable updates to be made to entity resources. - + class does the basic integration of all components of the server system. A new data service that uses system defaults for authorization and caching is created by defining a class that derives from the class and by referencing a compatible data model. + + The type of the must expose at least one property that returns an entity set that is an collection of entity types. This class must also implement the interface to enable updates to be made to entity resources. + ]]> @@ -62,11 +62,11 @@ Creates a new data service that deploys data of the type indicated by the template class. - class and by referencing a compatible data model. - + class and by referencing a compatible data model. + ]]> @@ -94,11 +94,11 @@ An instance of . Attaches the data service host to the data service identified by the parameter . - host attached is used by the data service to process requests. There is no requirement to set up a host when the data service is hosted in Windows Communication Foundation (WCF). - + host attached is used by the data service to process requests. There is no requirement to set up a host when the data service is hosted in Windows Communication Foundation (WCF). + ]]> @@ -124,11 +124,11 @@ Creates a data source of the template class that will be used by the data service. An instance of the data source. - @@ -153,11 +153,11 @@ Gets the data source instance currently being used to process the request. The data source instance for the service. - @@ -185,11 +185,11 @@ Exception arguments. Called when an exception is raised while processing a request. - @@ -272,11 +272,11 @@ Processes an HTTP request. - method should be invoked before you call to get request information and build the response. - + method should be invoked before you call to get request information and build the response. + ]]> diff --git a/xml/System.Data.Services/ExpandSegment.xml b/xml/System.Data.Services/ExpandSegment.xml index 22353aa566b..853f4538a25 100644 --- a/xml/System.Data.Services/ExpandSegment.xml +++ b/xml/System.Data.Services/ExpandSegment.xml @@ -23,25 +23,25 @@ The segment of a query that indicates whether data should be returned inline instead of as deferred content. - @@ -181,11 +181,11 @@ http://host/service.svc/Orders?$expand=OrderLines Gets the maximum number of results expected. The integer value that indicates maximum number of results. - + 1 elements. - + + 1 elements. + ]]> diff --git a/xml/System.Data.Services/HandleExceptionArgs.xml b/xml/System.Data.Services/HandleExceptionArgs.xml index 4a73e486b7e..2108e736d32 100644 --- a/xml/System.Data.Services/HandleExceptionArgs.xml +++ b/xml/System.Data.Services/HandleExceptionArgs.xml @@ -49,11 +49,11 @@ Gets or sets the exception that will be processed and returned in the response. The exception that will be processed and returned in the response. - , the message of the exception will always be returned to the client, regardless of the value. If is true, the inner exceptions will also be returned to the client; otherwise only the message will be returned. - + , the message of the exception will always be returned to the client, regardless of the value. If is true, the inner exceptions will also be returned to the client; otherwise only the message will be returned. + ]]> @@ -84,11 +84,11 @@ Gets the response content type. The string value that indicates the response format. - @@ -141,11 +141,11 @@ Gets a value indicating whether the response has been written. Boolean value that indicates whether response has been written. - @@ -180,11 +180,11 @@ Gets or sets a Boolean value that indicates whether verbose errors will be returned. The Boolean value that indicates whether verbose errors will be returned. - is set to true, all exception details will be returned in the response. Security Note: Setting this value to true may disclose information that should be private to the service. - + is set to true, all exception details will be returned in the response. Security Note: Setting this value to true may disclose information that should be private to the service. + ]]> diff --git a/xml/System.Data.Services/IDataServiceConfiguration.xml b/xml/System.Data.Services/IDataServiceConfiguration.xml index 20b5f0514ba..2507797b8ef 100644 --- a/xml/System.Data.Services/IDataServiceConfiguration.xml +++ b/xml/System.Data.Services/IDataServiceConfiguration.xml @@ -17,7 +17,7 @@ classes to configure the service by implementing a static method named InitializeService, returning void, and taking a single argument of type . The configuration object may only be used during the call to service initialization. + This type is used by classes to configure the service by implementing a static method named InitializeService, returning void, and taking a single argument of type . The configuration object may only be used during the call to service initialization. ]]> diff --git a/xml/System.Data.Services/IExpandProvider.xml b/xml/System.Data.Services/IExpandProvider.xml index 9b12fa5187a..9a13ecb9604 100644 --- a/xml/System.Data.Services/IExpandProvider.xml +++ b/xml/System.Data.Services/IExpandProvider.xml @@ -42,13 +42,13 @@ Applies expansions to the specified parameter. An object of the same type as the supplied object that includes the specified . - method may modify the `expandPaths` to indicate which expansions are included. - - The returned may implement the interface to provide enumerable objects for the expansions; otherwise, the expanded information is expected to be found directly in the enumerated objects. - + method may modify the `expandPaths` to indicate which expansions are included. + + The returned may implement the interface to provide enumerable objects for the expansions; otherwise, the expanded information is expected to be found directly in the enumerated objects. + ]]> diff --git a/xml/System.Data.Services/IUpdatable.xml b/xml/System.Data.Services/IUpdatable.xml index 7e083acdfe8..3052b03290b 100644 --- a/xml/System.Data.Services/IUpdatable.xml +++ b/xml/System.Data.Services/IUpdatable.xml @@ -14,17 +14,17 @@ An interface used to insert or update a resource by the HTTP POST method. - interface is resource independent. The methods that return objects representing resources can return anything. - - The returned object is an opaque object that represents the resource. To use the reference to read or update a value, the same opaque object is passed back to . - - Implementation of must track the mapping between this opaque object to the object it represents. When the resource is serialized and a common language runtime (CLR) instance of the correct type is needed, the ResolveResource method on is called with the opaque object. - - To serialize the object, call the method on . - + interface is resource independent. The methods that return objects representing resources can return anything. + + The returned object is an opaque object that represents the resource. To use the reference to read or update a value, the same opaque object is passed back to . + + Implementation of must track the mapping between this opaque object to the object it represents. When the resource is serialized and a common language runtime (CLR) instance of the correct type is needed, the ResolveResource method on is called with the opaque object. + + To serialize the object, call the method on . + ]]> @@ -106,13 +106,13 @@ Creates the resource of the specified type and that belongs to the specified container. The object representing a resource of specified type and belonging to the specified container. - is called to insert a new resource by the HTTP POST method. The first parameter points to the container that the resource belongs to and the second parameter is the namespace-qualified name of the resource type that needs to be created. - - The second parameter is most useful when using inheritance. The return type need not be the actual CLR instance of the resource. It can be anything, for example, a cookie, that the implementation requires. - + is called to insert a new resource by the HTTP POST method. The first parameter points to the container that the resource belongs to and the second parameter is the namespace-qualified name of the resource type that needs to be created. + + The second parameter is most useful when using inheritance. The return type need not be the actual CLR instance of the resource. It can be anything, for example, a cookie, that the implementation requires. + ]]> @@ -140,11 +140,11 @@ The resource to be deleted. Deletes the specified resource. - or . - + or . + ]]> @@ -203,11 +203,11 @@ Gets the value of the specified property on the target object. The value of the object. - @@ -239,11 +239,11 @@ The property value that needs to be removed. Removes the specified value from the collection. - @@ -298,13 +298,13 @@ Returns the instance of the resource represented by the specified resource object. The instance of the resource represented by the specified resource object. - or API into the CLR instance. This is normally called after to serialize the resource for POST methods. - - This method is also called if there are update interceptors invoked with the common language runtime (CLR) resource instances. It can be used if the provider supports optimistic concurrency and the resource type has concurrency tokens defined by in a CLR-based provider. - + or API into the CLR instance. This is normally called after to serialize the resource for POST methods. + + This method is also called if there are update interceptors invoked with the common language runtime (CLR) resource instances. It can be used if the provider supports optimistic concurrency and the resource type has concurrency tokens defined by in a CLR-based provider. + ]]> @@ -329,11 +329,11 @@ Saves all the changes that have been made by using the APIs. - implementation must track all changes until is called and then save all changes when is called. The implementation is expected to save all of the changes or to reject all of the changes together. - + implementation must track all changes until is called and then save all changes when is called. The implementation is expected to save all of the changes or to reject all of the changes together. + ]]> diff --git a/xml/System.Data.Sql/SqlDataSourceEnumerator.xml b/xml/System.Data.Sql/SqlDataSourceEnumerator.xml index d74b39ee497..d33d169badc 100644 --- a/xml/System.Data.Sql/SqlDataSourceEnumerator.xml +++ b/xml/System.Data.Sql/SqlDataSourceEnumerator.xml @@ -163,7 +163,7 @@ class Program ## Examples - The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the method to filter the rows in the table returned by the method. + The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the method to filter the rows in the table returned by the method. ```vb Imports System.Data.Sql diff --git a/xml/System.Data.Sql/SqlNotificationRequest.xml b/xml/System.Data.Sql/SqlNotificationRequest.xml index d94f073bf66..16f2ea096aa 100644 --- a/xml/System.Data.Sql/SqlNotificationRequest.xml +++ b/xml/System.Data.Sql/SqlNotificationRequest.xml @@ -71,7 +71,7 @@ object, that instance must have its and properties initialized before assigning the object to a object's property. The default values used by the constructor are NULL (`Nothing` in Visual Basic) for the , an empty string for the , and zero for the . + If the parameterless constructor is used to create a object, that instance must have its and properties initialized before assigning the object to a object's property. The default values used by the constructor are NULL (`Nothing` in Visual Basic) for the , an empty string for the , and zero for the . ]]> diff --git a/xml/System.Data.SqlClient/SqlBulkCopy.xml b/xml/System.Data.SqlClient/SqlBulkCopy.xml index 979e309a3c8..853e2d581b1 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopy.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopy.xml @@ -312,18 +312,18 @@ rows have been processed or there are no more rows to send to the destination data source. + A batch is complete when rows have been processed or there are no more rows to send to the destination data source. - Zero (the default) indicates that each operation is a single batch. + Zero (the default) indicates that each operation is a single batch. - If the instance has been declared without the option in effect, rows are sent to the server rows at a time, but no transaction-related action is taken. If is in effect, each batch of rows is inserted as a separate transaction. + If the instance has been declared without the option in effect, rows are sent to the server rows at a time, but no transaction-related action is taken. If is in effect, each batch of rows is inserted as a separate transaction. - The property can be set at any time. If a bulk copy is already in progress, the current batch is sized according to the previous batch size. Subsequent batches use the new size. If the is initially zero and changed while a operation is already in progress, that operation loads the data as a single batch. Any subsequent operations on the same instance use the new . + The property can be set at any time. If a bulk copy is already in progress, the current batch is sized according to the previous batch size. Subsequent batches use the new size. If the is initially zero and changed while a operation is already in progress, that operation loads the data as a single batch. Any subsequent operations on the same instance use the new . ## Examples - The following console application demonstrates how to bulk load data in batches of 50 rows. For an example illustrating how works with a transaction, see [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations). + The following console application demonstrates how to bulk load data in batches of 50 rows. For an example illustrating how works with a transaction, see [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations). In this example, the source data is first read from a SQL Server table to a instance. The source data does not have to be located on SQL Server; you can use any data source that can be read to an or loaded to a . @@ -424,16 +424,16 @@ on the object, no other operation will succeed. Calls to the method will throw an . + After you call a on the object, no other operation will succeed. Calls to the method will throw an . - Calling the method from the event causes an to be thrown. + Calling the method from the event causes an to be thrown. Note that open instances are closed implicitly at the end of a `using` block. ## Examples - The following example uses the same instance to add sales orders and their associated details to two destination tables. Because the **AdventureWorks** sales order tables are large, the sample reads only orders placed by a certain account number and bulk copies those orders and details to the destination tables. The method is used only after both bulk copy operations are complete. + The following example uses the same instance to add sales orders and their associated details to two destination tables. Because the **AdventureWorks** sales order tables are large, the sample reads only orders placed by a certain account number and bulk copies those orders and details to the destination tables. The method is used only after both bulk copy operations are complete. > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. @@ -479,7 +479,7 @@ collection is unnecessary. However, if the column counts differ, or the ordinal positions are not consistent, you must use to make sure that data is copied into the correct columns. + If the data source and the destination table have the same number of columns, and the ordinal position of each source column within the data source matches the ordinal position of the corresponding destination column, the collection is unnecessary. However, if the column counts differ, or the ordinal positions are not consistent, you must use to make sure that data is copied into the correct columns. During the execution of a bulk copy operation, this collection can be accessed, but it cannot be changed. Any attempt to change it will throw an . @@ -522,11 +522,11 @@ has not been set when is called, an is thrown. + If has not been set when is called, an is thrown. - If is modified while a operation is running, the change does not affect the current operation. The new value is used the next time a method is called. + If is modified while a operation is running, the change does not affect the current operation. The new value is used the next time a method is called. - is a three-part name (`..`). You can qualify the table name with its database and owning schema if you choose. However, if the table name uses an underscore ("_") or any other special characters, you must escape the name using surrounding brackets as in (`[..]`). For more information, see [Database Identifiers](/sql/relational-databases/databases/database-identifiers). + is a three-part name (`..`). You can qualify the table name with its database and owning schema if you choose. However, if the table name uses an underscore ("_") or any other special characters, you must escape the name using surrounding brackets as in (`[..]`). For more information, see [Database Identifiers](/sql/relational-databases/databases/database-identifiers). You can bulk-copy data to a temporary table by using a value such as `tempdb..#table` or `tempdb..#table` for the property. @@ -581,7 +581,7 @@ is `true`, reads from an object using , optimizing memory usage by using the streaming capabilities. When it's set to false, the class loads all the data returned by the object into memory before sending it to SQL Server or SQL Azure. + When is `true`, reads from an object using , optimizing memory usage by using the streaming capabilities. When it's set to false, the class loads all the data returned by the object into memory before sending it to SQL Server or SQL Azure. ]]> @@ -621,7 +621,7 @@ ## Remarks This property is designed for user interface components that illustrate the progress of a bulk copy operation. It indicates the number of rows to be processed before generating a notification event. The property can be set at any time, even while a bulk copy operation is underway. Changes made during a bulk copy operation take effect after the next notification. The new setting applies to all subsequent operations on the same instance. - If is set to a number less than zero, an is thrown. + If is set to a number less than zero, an is thrown. @@ -673,9 +673,9 @@ and are independent. Receipt of a event does not imply that any rows have been sent to the server or committed. + Note that the settings of and are independent. Receipt of a event does not imply that any rows have been sent to the server or committed. - You cannot call SqlBulkCopy.Close () or SqlConnection.Close () from this event. Doing this will cause an being thrown, and the object state will not change. If the user wants to cancel the operation from the event, the property of the can be used. (See [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations) for examples that use the property.) + You cannot call SqlBulkCopy.Close () or SqlConnection.Close () from this event. Doing this will cause an being thrown, and the object state will not change. If the user wants to cancel the operation from the event, the property of the can be used. (See [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations) for examples that use the property.) No action, such as transaction activity, is supported in the connection during the execution of the bulk copy operation, and it is recommended that you not use the same connection used during the event. However, you can open a different connection. @@ -756,7 +756,7 @@ makes the connection busy. If MARS is enabled, you can interleave calls to with other commands in the same connection. + If multiple active result sets (MARS) is disabled, makes the connection busy. If MARS is enabled, you can interleave calls to with other commands in the same connection. ]]> @@ -829,7 +829,7 @@ ## Remarks While the bulk copy operation is in progress, the associated destination is busy serving it, and no other operations can be performed on the connection. - The collection maps from the columns to the destination database table. + The collection maps from the columns to the destination database table. @@ -884,7 +884,7 @@ While the bulk copy operation is in progress, the associated destination is busy serving it, and no other operations can be performed on the connection. - The collection maps from the columns to the destination database table. + The collection maps from the columns to the destination database table. @@ -935,13 +935,13 @@ or a similar call, so the next available row is the first row. To process multiple results, call on the data reader and call again. + The copy operation starts at the next available row in the reader. Most of the time, the reader was just returned by or a similar call, so the next available row is the first row. To process multiple results, call on the data reader and call again. - Note that using modifies the state of the reader. The method will call until it returns false, the operation is aborted, or an error occurs. This means that the data reader will be in a different state, probably at the end of the result set, when the operation is complete. + Note that using modifies the state of the reader. The method will call until it returns false, the operation is aborted, or an error occurs. This means that the data reader will be in a different state, probably at the end of the result set, when the operation is complete. While the bulk copy operation is in progress, the associated destination is busy serving it, and no other operations can be performed on the connection. - The collection maps from the data reader columns to the destination database table. + The collection maps from the data reader columns to the destination database table. @@ -999,14 +999,14 @@ While the bulk copy operation is in progress, the associated destination is busy serving it, and no other operations can be performed on the connection. - The collection maps from the columns to the destination database table. + The collection maps from the columns to the destination database table. ## Examples The following Console application demonstrates how to bulk load only the rows in a that match a specified state. In this case, only unchanged rows are added. The destination table is a table in the **AdventureWorks** database. - In this example, a is created at run time and three rows are added to it. Before the method is executed, one of the rows is edited. The method is called with a `DataRowState.Unchanged` `rowState` argument, so only the two unchanged rows are bulk copied to the destination. + In this example, a is created at run time and three rows are added to it. Before the method is executed, one of the rows is edited. The method is called with a `DataRowState.Unchanged` `rowState` argument, so only the two unchanged rows are bulk copied to the destination. > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. @@ -1032,7 +1032,7 @@ makes the connection busy. If MARS is enabled, you can interleave calls to with other commands in the same connection. + If multiple active result sets (MARS) is disabled, makes the connection busy. If MARS is enabled, you can interleave calls to with other commands in the same connection. The number of rows that are rolled back when one fails depends on several things: @@ -1040,9 +1040,9 @@ - If you have your own transaction. -- The value of . +- The value of . - When there is an error while sending data to the server, the current batch (as specified by ) will be rolled back. If is not specified and you have your own transaction, the entire transaction will be rolled back (which includes all previous batches as well). + When there is an error while sending data to the server, the current batch (as specified by ) will be rolled back. If is not specified and you have your own transaction, the entire transaction will be rolled back (which includes all previous batches as well). Use to know how many rows were copied to the server. diff --git a/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml b/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml index 4c95c85abd1..74b95d0e662 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml @@ -38,9 +38,9 @@ ## Remarks Column mappings define the mapping between data source and the target table. - If mappings are not defined - that is, the collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an will be thrown. + If mappings are not defined - that is, the collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an will be thrown. - If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. + If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. You can refer to source and target columns by either name or ordinal. You can also mix by-name and by-ordinal column references in the same mappings collection. @@ -341,7 +341,7 @@ and properties are mutually exclusive. The last value set takes precedence. + The and properties are mutually exclusive. The last value set takes precedence. @@ -392,7 +392,7 @@ and properties are mutually exclusive. The last value set takes precedence. + The and properties are mutually exclusive. The last value set takes precedence. @@ -443,7 +443,7 @@ and properties are mutually exclusive. The last value set takes precedence. + The and properties are mutually exclusive. The last value set takes precedence. @@ -494,7 +494,7 @@ and properties are mutually exclusive. The last value set takes precedence. + The and properties are mutually exclusive. The last value set takes precedence. diff --git a/xml/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection.xml b/xml/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection.xml index e1c80877851..356fc2ac155 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection.xml @@ -49,28 +49,28 @@ Collection of objects that inherits from . - collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an is thrown. - - If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. - - You can refer to source and target columns by either name or ordinal. You can mix by-name and by-ordinal column references in the same mappings collection. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. are added to the for the object to create a column map for the bulk copy. - + collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an is thrown. + + If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. + + You can refer to source and target columns by either name or ordinal. You can mix by-name and by-ordinal column references in the same mappings collection. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. are added to the for the object to create a column map for the bulk copy. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingCollection/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -120,17 +120,17 @@ Adds the specified mapping to the . A object. - objects are used to create a column map for the bulk copy. - + objects are used to create a column map for the bulk copy. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMapping/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -172,22 +172,22 @@ Creates a new and adds it to the collection, using ordinals to specify both source and destination columns. A column mapping. - is thrown. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy using the ordinal position of the source and destination columns. - + is thrown. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy using the ordinal position of the source and destination columns. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingCollectionOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -229,22 +229,22 @@ Creates a new and adds it to the collection, using an ordinal for the source column and a string for the destination column. A column mapping. - is thrown. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + is thrown. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingIndexColName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source2.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -286,22 +286,22 @@ Creates a new and adds it to the collection, using a column name to describe the source column and an ordinal to specify the destination column. A column mapping. - is thrown. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + is thrown. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingColNameIndex/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Add/source1.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -343,22 +343,22 @@ Creates a new and adds it to the collection, using column names to specify both source and destination columns. A column mapping. - is thrown. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. The code creates a object by specifying the column names. - + is thrown. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. The code creates a object by specifying the column names. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingCollection/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -400,24 +400,24 @@ Clears the contents of the collection. - method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must clear the after the method and before processing the next bulk copy. - - Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. - - - -## Examples - The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. The method must be used after the first bulk copy is performed and before the next bulk copy's column mappings are defined. - + method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must clear the after the method and before processing the next bulk copy. + + Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. + + + +## Examples + The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. The method must be used after the first bulk copy is performed and before the next bulk copy's column mappings are defined. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingOrdersDetails/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Clear/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Clear/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -703,24 +703,24 @@ object to be removed from the collection. Removes the specified element from the . - method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must remove mappings that no longer apply after the method is called and before defining mapping for the next bulk copy. You can clear the entire collection by using the method, or remove mappings individually using the method or the method. - - Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. - - - -## Examples - The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. Both bulk copies include a mapping for the **SalesOrderID**, so rather than clearing the entire collection between bulk copy operations, the example removes all mappings except for the **SalesOrderID** mapping and then adds the appropriate mappings for the second bulk copy operation. - + method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must remove mappings that no longer apply after the method is called and before defining mapping for the next bulk copy. You can clear the entire collection by using the method, or remove mappings individually using the method or the method. + + Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. + + + +## Examples + The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. Both bulk copies include a mapping for the **SalesOrderID**, so rather than clearing the entire collection between bulk copy operations, the example removes all mappings except for the **SalesOrderID** mapping and then adds the appropriate mappings for the second bulk copy operation. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingRemove/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Remove/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/Remove/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -765,24 +765,24 @@ The zero-based index of the object to be removed from the collection. Removes the mapping at the specified index from the collection. - method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must remove mappings that no longer apply after the method is called and before defining mapping for the next bulk copy. You can clear the entire collection by using the method, or remove mappings individually using the method or the method. - - Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. - - - -## Examples - The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. Both bulk copies include a mapping for the **SalesOrderID**, so rather than clearing the entire collection between bulk copy operations, the example removes all mappings except for the **SalesOrderID** mapping and then adds the appropriate mappings for the second bulk copy operation. - + method is most commonly used when you use a single instance to process more than one bulk copy operation. If you create column mappings for one bulk copy operation, you must remove mappings that no longer apply after the method is called and before defining mapping for the next bulk copy. You can clear the entire collection by using the method, or remove mappings individually using the method or the method. + + Performing several bulk copies using the same instance will usually be more efficient from a performance point of view than using a separate for each operation. + + + +## Examples + The following example performs two bulk copy operations. The first operation copies sales order header information, and the second copies sales order details. Although not strictly necessary in this example (because the ordinal positions of the source and destination columns do match), the example defines column mappings for each bulk copy operation. Both bulk copies include a mapping for the **SalesOrderID**, so rather than clearing the entire collection between bulk copy operations, the example removes all mappings except for the **SalesOrderID** mapping and then adds the appropriate mappings for the second bulk copy operation. + > [!IMPORTANT] > This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT ... SELECT` statement to copy the data. - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingRemoveAt/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -825,14 +825,14 @@ is less than zero. - is multidimensional. - - -or- - - The number of elements in the source is greater than the available space from to the end of the destination . - - -or- - + is multidimensional. + + -or- + + The number of elements in the source is greater than the available space from to the end of the destination . + + -or- + The type of the source cannot be cast automatically to the type of the destination . @@ -939,10 +939,10 @@ This member is an explicit interface member implementation. It can be used only Adds an item to the . The position into which the new element was inserted, or -1 to indicate that the item was not inserted into the collection. To be added. - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. @@ -1044,10 +1044,10 @@ This member is an explicit interface member implementation. It can be used only To be added. is not a valid index in the . - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. is null reference in the . @@ -1191,10 +1191,10 @@ This member is an explicit interface member implementation. It can be used only The object to remove from the . Removes the first occurrence of a specific object from the . To be added. - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. diff --git a/xml/System.Data.SqlClient/SqlBulkCopyOptions.xml b/xml/System.Data.SqlClient/SqlBulkCopyOptions.xml index 4122c71c6f2..71ca6abc313 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopyOptions.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopyOptions.xml @@ -41,7 +41,7 @@ enumeration when you construct a instance to change how the methods for that instance behave. + You can use the enumeration when you construct a instance to change how the methods for that instance behave. diff --git a/xml/System.Data.SqlClient/SqlClientPermission.xml b/xml/System.Data.SqlClient/SqlClientPermission.xml index 27cf77d6167..8b6ec2736f3 100644 --- a/xml/System.Data.SqlClient/SqlClientPermission.xml +++ b/xml/System.Data.SqlClient/SqlClientPermission.xml @@ -52,7 +52,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. + The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. > [!NOTE] > When using code access security permissions for ADO.NET, the correct pattern is to start with the most restrictive case (no permissions at all) and then add the specific permissions that are needed for the particular task that the code needs to perform. The opposite pattern, starting with all permissions and then denying a specific permission, is not secure, because there are many ways of expressing the same connection string. For example, if you start with all permissions and then attempt to deny the use of the connection string "server=someserver", the string "server=someserver.mycompany.com" would still be allowed. By always starting by granting no permissions at all, you reduce the chances that there are holes in the permission set. @@ -204,7 +204,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). ]]> diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml index 37cbdc9c76e..13a0530a18a 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionCngProvider.xml @@ -151,7 +151,7 @@ method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. + The method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. ]]> diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml index 47476d07bb1..4bdf234c54a 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionCspProvider.xml @@ -151,7 +151,7 @@ method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. + The method must be implemented by the corresponding key store providers. should use an asymmetric key identified by a key path and sign the masterkey metadata consisting of `masterKeyPath`, `allowEnclaveComputations`, and providerName. ]]> diff --git a/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml b/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml index 7b47d76c9ac..993de9f0daa 100644 --- a/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml +++ b/xml/System.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml @@ -126,9 +126,9 @@ The encrypted column encryption key. method doesn't break applications that rely on an old API, it throws a exception by default. + To ensure that the method doesn't break applications that rely on an old API, it throws a exception by default. - The method will be used by client tools that generate Column Master Keys (CMK) for customers. must be implemented by the corresponding key store providers that wish to use enclaves with [Always Encrypted](https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine). + The method will be used by client tools that generate Column Master Keys (CMK) for customers. must be implemented by the corresponding key store providers that wish to use enclaves with [Always Encrypted](https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine). ]]> diff --git a/xml/System.Data.SqlClient/SqlCommand.xml b/xml/System.Data.SqlClient/SqlCommand.xml index a232fd34b18..c63fd06d254 100644 --- a/xml/System.Data.SqlClient/SqlCommand.xml +++ b/xml/System.Data.SqlClient/SqlCommand.xml @@ -86,13 +86,13 @@ |Item|Description| |----------|-----------------| -||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , generally executing commands such as INSERT, DELETE, UPDATE, and SET statements. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| -||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more results sets from the server. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| -||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this . Each call to `BeginExecuteXmlReader` must be paired with a call to `EndExecuteXmlReader`, which finishes the operation, typically on a separate thread, and returns an object.| -||Executes commands that return rows. For increased performance, invokes commands using the Transact-SQL `sp_executesql` system stored procedure. Therefore, might not have the effect that you want if used to execute commands such as Transact-SQL SET statements.| -||Executes commands such as Transact-SQL INSERT, DELETE, UPDATE, and SET statements.| -||Retrieves a single value (for example, an aggregate value) from a database.| -||Sends the to the and builds an object.| +||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , generally executing commands such as INSERT, DELETE, UPDATE, and SET statements. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| +||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more results sets from the server. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| +||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this . Each call to `BeginExecuteXmlReader` must be paired with a call to `EndExecuteXmlReader`, which finishes the operation, typically on a separate thread, and returns an object.| +||Executes commands that return rows. For increased performance, invokes commands using the Transact-SQL `sp_executesql` system stored procedure. Therefore, might not have the effect that you want if used to execute commands such as Transact-SQL SET statements.| +||Executes commands such as Transact-SQL INSERT, DELETE, UPDATE, and SET statements.| +||Retrieves a single value (for example, an aggregate value) from a database.| +||Sends the to the and builds an object.| You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. @@ -479,10 +479,10 @@ class Program { |Properties|Initial value| |----------------|-------------------| -||empty string ("")| -||30| -||`CommandType.Text`| -||Null| +||empty string ("")| +||30| +||`CommandType.Text`| +||Null| You can change the value for any of these properties through a separate call to the property. @@ -538,10 +538,10 @@ class Program { |Properties|Initial value| |----------------|-------------------| -||`cmdText`| -||30| -||`CommandType.Text`| -||null| +||`cmdText`| +||30| +||`CommandType.Text`| +||null| You can change the value for any of these properties through a separate call to the property. @@ -599,10 +599,10 @@ class Program { |Properties|Initial value| |----------------|-------------------| -||`cmdText`| -||30| -||`CommandType.Text`| -||A new that is the value for the `connection` parameter.| +||`cmdText`| +||30| +||`CommandType.Text`| +||A new that is the value for the `connection` parameter.| You can change the value for any of these parameters by setting the related property. @@ -662,10 +662,10 @@ class Program { |Properties|Initial value| |----------------|-------------------| -||`cmdText`| -||30| -||`CommandType.Text`| -||A new that is the value for the `connection` parameter.| +||`cmdText`| +||30| +||`CommandType.Text`| +||A new that is the value for the `connection` parameter.| You can change the value for any of these parameters by setting the related property. @@ -745,11 +745,11 @@ class Program { method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . This method ignores the property. @@ -822,9 +822,9 @@ The closed or dropped durin method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `asyncStateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `asyncStateObject` parameter, and your callback procedure can retrieve this information using the property. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. @@ -837,7 +837,7 @@ The closed or dropped durin ## Examples - The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of several seconds (emulating a long-running command). + The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of several seconds (emulating a long-running command). This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called. @@ -913,13 +913,13 @@ A other than **Xml method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. + Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. @@ -990,15 +990,15 @@ A timeout occurred during a streaming operation. For more information about stre method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. The `behavior` parameter lets you specify options that control the behavior of the command and its connection. These values can be combined together (using the programming language's `OR` operator); generally, developers use the `CommandBehavior.CloseConnection` value to make sure that the connection is closed by the runtime when the is closed. - Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. + Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . - If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. @@ -1072,24 +1072,24 @@ A timeout occurred during a streaming operation. For more information about stre method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed cause the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed cause the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. - Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. + Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. Because the callback procedure executes from within a background thread supplied by the Microsoft .NET runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. For example, you must not interact with a form's contents from within your callback procedure; should you have to update the form, you must switch back to the form's thread in order to do your work. The example in this topic demonstrates this behavior. All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure. - If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. ## Examples - The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing object as the `stateObject` parameter; doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . + The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing object as the `stateObject` parameter; doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called. @@ -1161,26 +1161,26 @@ A other than **Xml method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. The `behavior` parameter lets you specify options that control the behavior of the command and its connection. These values can be combined together (using the programming language's `Or` operator); generally, developers use the `CloseConnection` value to make sure that the connection is closed by the runtime when the is closed. Developers can also optimize the behavior of the by specifying the `SingleRow` value when it is known in advance that the Transact-SQL statement or stored procedure only returns a single row. - Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. + Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. Because the callback procedure executes from within a background thread supplied by the Microsoft .NET common language runtime, it is very important that you take a rigorous approach to handling cross-thread interactions from within your applications. For example, you must not interact with a form's contents from within your callback procedure--should you have to update the form, you must switch back to the form's thread in order to do your work. The example in this topic demonstrates this behavior. All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure. - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. ## Examples - The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing object as the `stateObject` parameter; doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . + The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). Because the sample executes the command asynchronously, the form remains responsive while awaiting the results. This example passes the executing object as the `stateObject` parameter; doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called. @@ -1258,11 +1258,11 @@ A other than **Xml method starts the process of asynchronously executing a Transact-SQL statement that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the `EndExecuteXmlReader` method to finish the operation and retrieve the XML returned by the command. The method returns immediately, but until the code executes the corresponding `EndExecuteXmlReader` method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the `EndExecuteXmlReader` before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the `EndExecuteXmlReader` method to finish the operation and retrieve the XML returned by the command. The method returns immediately, but until the code executes the corresponding `EndExecuteXmlReader` method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the `EndExecuteXmlReader` before the command's execution is completed causes the object to block until the execution is finished. The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns `ntext` data that contains valid XML. - A typical query can be formatted as in the following C# example: + A typical query can be formatted as in the following C# example: ```csharp SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.Contact FOR XML AUTO, XMLDATA", SqlConn); @@ -1274,9 +1274,9 @@ SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. - Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . - If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. @@ -1349,34 +1349,34 @@ The closed or dropped durin method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the requested XML data. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. + The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the requested XML data. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns data that contains valid XML. This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. + The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns data that contains valid XML. This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. - A typical query can be formatted as in the following C# example: + A typical query can be formatted as in the following C# example: ```csharp SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Contact FOR XML AUTO, XMLDATA", SqlConn); ``` - This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. + This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. The multiple active result set (MARS) feature lets multiple actions use the same connection. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters is sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure. - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. This method ignores the property. ## Examples - The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). This example passes the executing object as the `stateObject` parameter--doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . + The following Windows application demonstrates the use of the method, executing a Transact-SQL statement that includes a delay of a few seconds (emulating a long-running command). This example passes the executing object as the `stateObject` parameter--doing so makes it simple to retrieve the object from within the callback procedure, so that the code can call the method corresponding to the initial call to . This example demonstrates many important techniques. This includes calling a method that interacts with the form from a separate thread. In addition, this example demonstrates how you must block users from executing a command multiple times concurrently, and how you must make sure that the form does not close before the callback procedure is called. @@ -1456,12 +1456,12 @@ The closed or dropped durin ## Remarks If there is nothing to cancel, nothing occurs. However, if there is a command in process, and the attempt to cancel fails, no exception is generated. - In some rare cases, if you call , then call (implicitly or explicitly) before calling , and then call , the cancel command will not be sent to SQL Server and the result set can continue to stream after you call . To avoid this, make sure that you call before closing the reader or connection. + In some rare cases, if you call , then call (implicitly or explicitly) before calling , and then call , the cancel command will not be sent to SQL Server and the result set can continue to stream after you call . To avoid this, make sure that you call before closing the reader or connection. ## Examples - The following example demonstrates the use of the method. + The following example demonstrates the use of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Cancel/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/Cancel/source.vb" id="Snippet1"::: @@ -1679,14 +1679,14 @@ SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID A value of 0 indicates no limit (an attempt to execute a command will wait indefinitely). > [!NOTE] -> The property will be ignored by older APM (Asynchronous Programming Model) asynchronous method calls such as . It will be honored by newer TAP (Task Asynchronous Programming) methods such as . +> The property will be ignored by older APM (Asynchronous Programming Model) asynchronous method calls such as . It will be honored by newer TAP (Task Asynchronous Programming) methods such as . - has no effect when the command is executed against a context connection (a opened with "context connection=true" in the connection string). + has no effect when the command is executed against a context connection (a opened with "context connection=true" in the connection string). > [!NOTE] > This property is the cumulative time-out (for all network packets that are read during the invocation of a method) for all network reads during command execution or processing of the results. A time-out can still occur after the first row is returned, and does not include user processing time, only network read time. > -> For example, with a 30 second time out, if requires two network packets, then it has 30 seconds to read both network packets. If you call again, it will have another 30 seconds to read any data that it requires. +> For example, with a 30 second time out, if requires two network packets, then it has 30 seconds to read both network packets. If you call again, it will have another 30 seconds to read any data that it requires. ```csharp using System; @@ -1777,7 +1777,7 @@ public class A { ## Remarks When you set the property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. - The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a SQL Statement or a stored procedure called with a of . In this case, named parameters must be used. For example: + The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a SQL Statement or a stored procedure called with a of . In this case, named parameters must be used. For example: SELECT * FROM Customers WHERE CustomerID = @CustomerID @@ -1856,7 +1856,7 @@ public class A { ## Remarks If the command is enlisted in an existing transaction, and the connection is changed, trying to execute the command will throw an . - If the property is not null and the transaction has already been committed or rolled back, is set to null. + If the property is not null and the transaction has already been committed or rolled back, is set to null. @@ -1942,7 +1942,7 @@ public class A { method is a strongly-typed version of . + The method is a strongly-typed version of . ]]> @@ -2163,12 +2163,12 @@ public class A { to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. + When you call to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. ## Examples - For examples demonstrating the use of the method, see . + For examples demonstrating the use of the method, see . ]]> @@ -2217,12 +2217,12 @@ In some situations, can be set to to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. + When you call to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. ## Examples - For examples demonstrating the use of the method, see . + For examples demonstrating the use of the method, see . ]]> @@ -2266,12 +2266,12 @@ In some situations, can be set to to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. + When you call to execute a Transact-SQL statement, you must call in order to complete the operation. If the process of executing the command has not yet finished, this method blocks until the operation is complete. Users can verify that the command has completed its operation by using the instance returned by the method. If a callback procedure was specified in the call to , this method must be called. ## Examples - For examples demonstrating the use of the method, see . + For examples demonstrating the use of the method, see . ]]> @@ -2397,9 +2397,9 @@ In some situations, can be set to to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. + You can use the to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. - Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. + Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. @@ -2412,7 +2412,7 @@ If no statements are detected that contribute to the count, the return value is ## Examples - The following example creates a and then executes it using . The example is passed a string that is a Transact-SQL statement (such as UPDATE, INSERT, or DELETE) and a string to use to connect to the data source. + The following example creates a and then executes it using . The example is passed a string that is a Transact-SQL statement (such as UPDATE, INSERT, or DELETE) and a string to use to connect to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteNonQuery Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: @@ -2555,14 +2555,14 @@ The closed or dropped durin property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . > [!NOTE] -> If a transaction is deadlocked, an exception may not be thrown until is called. +> If a transaction is deadlocked, an exception may not be thrown until is called. The multiple active result set (MARS) feature allows for multiple actions using the same connection. - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. @@ -2638,14 +2638,14 @@ The closed or dropped durin property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . > [!NOTE] > Use to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. The multiple active result set (MARS) feature allows for multiple actions using the same connection. - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. @@ -3020,9 +3020,9 @@ A timeout occurred during a streaming operation. For more information about stre method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations that you need to generate the single value using the data returned by a . + Use the method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations that you need to generate the single value using the data returned by a . - A typical query can be formatted as in the following C# example: + A typical query can be formatted as in the following C# example: ```csharp cmd.CommandText = "SELECT COUNT(*) FROM dbo.region"; @@ -3030,7 +3030,7 @@ Int32 count = (Int32) cmd.ExecuteScalar(); ``` ## Examples - The following example creates a and then executes it using . The example is passed a string representing a new value to be inserted into a table, and a string to use to connect to the data source. The function returns the new **Identity** column value if a new row was inserted, 0 on failure. + The following example creates a and then executes it using . The example is passed a string representing a new value to be inserted into a table, and a string to use to connect to the data source. The function returns the new **Identity** column value if a new row was inserted, 0 on failure. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.ExecuteScalar/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/ExecuteScalar/source.vb" id="Snippet1"::: @@ -3166,23 +3166,23 @@ A timeout occurred during a streaming operation. For more information about stre ## Remarks The **XmlReader** returned by this method does not support asynchronous operations. - The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, can also specify a statement that returns `ntext` or `nvarchar` data that contains valid XML, or the contents of a column defined with the `xml` data type. + The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, can also specify a statement that returns `ntext` or `nvarchar` data that contains valid XML, or the contents of a column defined with the `xml` data type. - A typical query can be formatted as in the following Microsoft Visual C# example: + A typical query can be formatted as in the following Microsoft Visual C# example: ```csharp SqlCommand command = new SqlCommand("SELECT * FROM dbo.Customers FOR XML AUTO, XMLDATA", SqlConn); ``` - This method can also be used to retrieve a single-row, single-column result set that contains XML data. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. + This method can also be used to retrieve a single-row, single-column result set that contains XML data. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. The multiple active result set (MARS) feature allows for multiple actions using the same connection. - If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. + If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. ## Examples - The following example creates a and then executes it using . The example is passed a string that is a Transact-SQL FOR XML SELECT statement, and a string to use to connect to the data source. + The following example creates a and then executes it using . The example is passed a string that is a Transact-SQL FOR XML SELECT statement, and a string to use to connect to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteXmlReader/CS/mysample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/ExecuteXmlReader/mysample.vb" id="Snippet1"::: @@ -3565,21 +3565,21 @@ A timeout occurred during a streaming operation. For more information about stre is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. + If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. - Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the property to the maximum size needed. returns an error if these conditions are not met. + Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the property to the maximum size needed. returns an error if these conditions are not met. > [!NOTE] -> If the database context is changed by executing the Transact-SQL `USE ` statement, or by calling the method, then must be called a second time. +> If the database context is changed by executing the Transact-SQL `USE ` statement, or by calling the method, then must be called a second time. - If you call an `Execute` method after calling , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + If you call an `Execute` method after calling , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. - Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . + Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . - Prior to Visual Studio 2010, threw an exception. Beginning in Visual Studio 2010, this method does not throw an exception. + Prior to Visual Studio 2010, threw an exception. Beginning in Visual Studio 2010, this method does not throw an exception. ## Examples - The following example demonstrates the use of the method. + The following example demonstrates the use of the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Prepare/CS/Source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/Prepare/Source.vb" id="Snippet1"::: @@ -3619,7 +3619,7 @@ A timeout occurred during a streaming operation. For more information about stre is 30 seconds. + The default value of the is 30 seconds. ]]> diff --git a/xml/System.Data.SqlClient/SqlCommandBuilder.xml b/xml/System.Data.SqlClient/SqlCommandBuilder.xml index cec4772d6ef..723cea9cd3f 100644 --- a/xml/System.Data.SqlClient/SqlCommandBuilder.xml +++ b/xml/System.Data.SqlClient/SqlCommandBuilder.xml @@ -42,13 +42,13 @@ The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved, such as after the first update, you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved, such as after the first update, you should call the method to update the metadata. The `SelectCommand` must also return at least one primary key or unique column. If none are present, an **InvalidOperation** exception is generated, and the commands are not generated. - The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. + The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. - If you call , the is disassociated from the , and the generated commands are no longer used. + If you call , the is disassociated from the , and the generated commands are no longer used. @@ -392,11 +392,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -437,11 +437,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -483,11 +483,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . + After the SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -518,11 +518,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -563,11 +563,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -609,11 +609,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -764,11 +764,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -806,11 +806,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). @@ -852,11 +852,11 @@ method for informational or troubleshooting purposes because it returns the object to be executed. + An application can use the method for informational or troubleshooting purposes because it returns the object to be executed. - You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . + You can also use as the basis of a modified command. For example, you might call and modify the value, and then explicitly set that on the . - After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . + After the Transact-SQL statement is first generated, the application must explicitly call if it changes the statement in any way. Otherwise, the will still be using information from the previous statement, which might not be correct. The Transact-SQL statements are first generated when the application calls either or . The default behavior, when generating parameter names, is to use `@p1`, `@p2`, and so on for the various parameters. Passing `true` for the `useColumnsForParameterNames` parameter lets you force the to generate parameters based on the column names instead. This succeeds only if the following conditions are met: @@ -989,7 +989,7 @@ ## Remarks > [!NOTE] -> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a DataAdapter. +> Although you cannot change the or properties after an insert, update, or delete command has been generated, you can change their settings after calling the `Update` method of a DataAdapter. ]]> @@ -1050,7 +1050,7 @@ ## Remarks > [!NOTE] -> Although you cannot change the or properties after an insert, update, or delete operation has been generated, you can change their settings after calling the `Update` method of a DataAdapter. +> Although you cannot change the or properties after an insert, update, or delete operation has been generated, you can change their settings after calling the `Update` method of a DataAdapter. ]]> diff --git a/xml/System.Data.SqlClient/SqlConnection.xml b/xml/System.Data.SqlClient/SqlConnection.xml index 3e1cdf65591..432f81f8109 100644 --- a/xml/System.Data.SqlClient/SqlConnection.xml +++ b/xml/System.Data.SqlClient/SqlConnection.xml @@ -69,7 +69,7 @@ When you create an instance of , all properties are set to their initial values. For a list of these values, see the constructor. - See for a list of the keywords in a connection string. + See for a list of the keywords in a connection string. If the goes out of scope, it won't be closed. Therefore, you must explicitly close the connection by calling `Close` or `Dispose`. `Close` and `Dispose` are functionally equivalent. If the connection pooling value `Pooling` is set to `true` or `yes`, the underlying connection is returned back to the connection pool. On the other hand, if `Pooling` is set to `false` or `no`, the underlying connection to the server is actually closed. @@ -108,7 +108,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ## Examples - The following example creates a and a . The is opened and set as the for the . The example then calls . To accomplish this, the is passed a SqlConnection and a query string that is a Transact-SQL INSERT statement. The connection is closed automatically when the code exits the using block. + The following example creates a and a . The is opened and set as the for the . The example then calls . To accomplish this, the is passed a SqlConnection and a query string that is a Transact-SQL INSERT statement. The connection is closed automatically when the code exits the using block. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteNonQuery Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: @@ -163,10 +163,10 @@ using (SqlConnection connection = new SqlConnection(connectionString)) |Properties|Initial value| |----------------|-------------------| -||empty string ("")| -||15| -||empty string ("")| -||empty string ("")| +||empty string ("")| +||15| +||empty string ("")| +||empty string ("")| You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. @@ -222,10 +222,10 @@ using (SqlConnection connection = new SqlConnection(connectionString)) |Properties|Initial value| |----------------|-------------------| -|| `connectionString` | -||15| -||empty string ("")| -||empty string ("")| +|| `connectionString` | +||15| +||empty string ("")| +||empty string ("")| You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. @@ -391,13 +391,13 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ## Remarks This command maps to the SQL Server implementation of BEGIN TRANSACTION. - You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. + You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. > [!NOTE] -> If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the method, use the overload that takes the `iso` parameter (). The isolation level set for a transaction persists after the transaction is completed and until the connection is closed or disposed. Setting the isolation level to **Snapshot** in a database where the snapshot isolation level is not enabled does not throw an exception. The transaction will complete using the default isolation level. +> If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the method, use the overload that takes the `iso` parameter (). The isolation level set for a transaction persists after the transaction is completed and until the connection is closed or disposed. Setting the isolation level to **Snapshot** in a database where the snapshot isolation level is not enabled does not throw an exception. The transaction will complete using the default isolation level. > [!CAUTION] -> If a transaction is started and a level 16 or higher error occurs on the server, the transaction will not be rolled back until the method is invoked. No exception is thrown on **ExecuteReader**. +> If a transaction is started and a level 16 or higher error occurs on the server, the transaction will not be rolled back until the method is invoked. No exception is thrown on **ExecuteReader**. > [!CAUTION] > When your query returns a large amount of data and calls `BeginTransaction`, a is thrown because SQL Server does not allow parallel transactions when using MARS. To avoid this problem, always associate a transaction with the command, the connection, or both before any readers are open. @@ -407,7 +407,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ## Examples - The following example creates a and a . It also demonstrates how to use the , a , and methods. + The following example creates a and a . It also demonstrates how to use the , a , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: @@ -462,10 +462,10 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ## Remarks This command maps to the SQL Server implementation of BEGIN TRANSACTION. - You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. + You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. > [!NOTE] -> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the SQL Server default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the Transact-SQL SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). +> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the SQL Server default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the Transact-SQL SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). @@ -473,7 +473,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) > When your query returns a large amount of data and calls `BeginTransaction`, a is thrown because SQL Server does not allow parallel transactions when using MARS. To avoid this problem, always associate a transaction with the command, the connection, or both before any readers are open. ## Examples - The following example creates a and a . It also demonstrates how to use the , a , and methods. + The following example creates a and a . It also demonstrates how to use the , a , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/BeginTransaction/source.vb" id="Snippet1"::: @@ -530,9 +530,9 @@ using (SqlConnection connection = new SqlConnection(connectionString)) The length of the `transactionName` parameter must not exceed 32 characters; otherwise an exception will be thrown. - The value in the `transactionName` parameter can be used in later calls to and in the `savePoint` parameter of the method. + The value in the `transactionName` parameter can be used in later calls to and in the `savePoint` parameter of the method. - You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. + You must explicitly commit or roll back the transaction using the or method. To make sure that the .NET Framework Data Provider for SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). @@ -540,7 +540,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) > When your query returns a large amount of data and calls `BeginTransaction`, a is thrown because SQL Server does not allow parallel transactions when using MARS. To avoid this problem, always associate a transaction with the command, the connection, or both before any readers are open. ## Examples - The following example creates a and a . It also demonstrates how to use the , a , and methods. + The following example creates a and a . It also demonstrates how to use the , a , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/BeginTransaction/source1.vb" id="Snippet1"::: @@ -597,12 +597,12 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ## Remarks This command maps to the SQL Server implementation of BEGIN TRANSACTION. - The value in the `transactionName` parameter can be used in later calls to and in the `savePoint` parameter of the method. + The value in the `transactionName` parameter can be used in later calls to and in the `savePoint` parameter of the method. - You must explicitly commit or roll back the transaction using the or method. To make sure that the SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. + You must explicitly commit or roll back the transaction using the or method. To make sure that the SQL Server transaction management model performs correctly, avoid using other transaction management models, such as the one provided by SQL Server. > [!NOTE] -> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the SQL Server default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the Transact-SQL SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). +> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the SQL Server default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the Transact-SQL SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). @@ -610,7 +610,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) > When your query returns a large amount of data and calls `BeginTransaction`, a is thrown because SQL Server does not allow parallel transactions when using MARS. To avoid this problem, always associate a transaction with the command, the connection, or both before any readers are open. ## Examples - The following example creates a and a . It also demonstrates how to use the , a , and methods. + The following example creates a and a . It also demonstrates how to use the , a , and methods. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction3 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/BeginTransaction/source2.vb" id="Snippet1"::: @@ -734,9 +734,9 @@ using (SqlConnection connection = new SqlConnection(connectionString)) [!INCLUDE[ROPC warning](~/includes/ropc-warning.md)] - The method changes the SQL Server password for the user indicated in the supplied `connectionString` parameter to the value supplied in the `newPassword` parameter. If the connection string includes the option for integrated security (that is, "Integrated Security=True" or the equivalent), an exception is thrown. + The method changes the SQL Server password for the user indicated in the supplied `connectionString` parameter to the value supplied in the `newPassword` parameter. If the connection string includes the option for integrated security (that is, "Integrated Security=True" or the equivalent), an exception is thrown. - To determine that the password has expired, calling the method raises a . In order to indicate that the password that is contained within the connection string must be reset, the property for the exception contains the status value 18487 or 18488. The first value (18487) indicates that the password has expired and the second (18488) indicates that the password must be reset before logging in. + To determine that the password has expired, calling the method raises a . In order to indicate that the password that is contained within the connection string must be reset, the property for the exception contains the status value 18487 or 18488. The first value (18487) indicates that the password has expired and the second (18488) indicates that the password must be reset before logging in. This method opens its own connection to the server, requests the password change, and closes the connection as soon as it has completed. This connection is not retrieved from or returned to the SQL Server connection pool. @@ -839,7 +839,7 @@ The connection string contains . resets (or empties) the connection pool. If there are connections in use at the time of the call, they are marked appropriately and will be discarded (instead of being returned to the pool) when is called on them. + resets (or empties) the connection pool. If there are connections in use at the time of the call, they are marked appropriately and will be discarded (instead of being returned to the pool) when is called on them. ]]> @@ -882,7 +882,7 @@ The connection string contains . clears the connection pool that is associated with the `connection`. If additional connections associated with `connection` are in use at the time of the call, they are marked appropriately and are discarded (instead of being returned to the pool) when is called on them. + clears the connection pool that is associated with the `connection`. If additional connections associated with `connection` are in use at the time of the call, they are marked appropriately and are discarded (instead of being returned to the pool) when is called on them. ]]> @@ -927,7 +927,7 @@ The connection string contains . works regardless of which version of the server you connect to, but extended events logs and entry on connectivity ring buffer errors will not be present in SQL Server 2008 R2 and earlier. + works regardless of which version of the server you connect to, but extended events logs and entry on connectivity ring buffer errors will not be present in SQL Server 2008 R2 and earlier. You can locate the connection ID in the extended events log to see if the failure was on the server if the extended event for logging connection ID is enabled. You can also locate the connection ID in the connection ring buffer for certain connection errors. If the connection ID is not in the connection ring buffer, you can assume a network error. @@ -977,12 +977,12 @@ The connection string contains . method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. + The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. > [!NOTE] -> Pending transactions started using Transact-SQL or are automatically rolled back when the connection is reset if connection pooling is enabled. If connection pooling is off, the transaction is rolled back after `SqlConnection.Close` is called. Transactions started through are controlled through the `System.Transactions` infrastructure, and are not affected by `SqlConnection.Close`. +> Pending transactions started using Transact-SQL or are automatically rolled back when the connection is reset if connection pooling is enabled. If connection pooling is off, the transaction is rolled back after `SqlConnection.Close` is called. Transactions started through are controlled through the `System.Transactions` infrastructure, and are not affected by `SqlConnection.Close`. - An application can call more than one time. No exception is generated. + An application can call more than one time. No exception is generated. If the goes out of scope, it won't be closed. Therefore, you must explicitly close the connection by calling `Close` or `Dispose`. `Close` and `Dispose` are functionally equivalent. If the connection pooling value `Pooling` is set to `true` or `yes`, the underlying connection is returned back to the connection pool. On the other hand, if `Pooling` is set to `false` or `no`, the underlying connection to the server is closed. @@ -1180,7 +1180,7 @@ The connection string contains . ## Remarks -The is similar to an OLE DB connection string, but is not identical. Unlike OLE DB or ADO, the connection string that is returned is the same as the user-set , minus security information if the Persist Security Info value is set to `false` (default). The .NET Framework Data Provider for SQL Server does not persist or return the password in a connection string unless you set Persist Security Info to `true`. +The is similar to an OLE DB connection string, but is not identical. Unlike OLE DB or ADO, the connection string that is returned is the same as the user-set , minus security information if the Persist Security Info value is set to `false` (default). The .NET Framework Data Provider for SQL Server does not persist or return the password in a connection string unless you set Persist Security Info to `true`. You can use the property to connect to a database. The following example illustrates a typical connection string. @@ -1190,11 +1190,11 @@ The is similar to Use the new to construct valid connection strings at run time. For more information, see [Connection String Builders](/dotnet/framework/data/adonet/connection-string-builders). - The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . + The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . To connect to a local computer, specify "(local)" for the server. If a server name is not specified, a connection will be attempted to the default instance on the local computer. - Resetting the on a closed connection resets all connection string values (and related properties) including the password. For example, if you set a connection string that includes "Database= AdventureWorks", and then reset the connection string to "Data Source=myserver;Integrated Security=true", the property is no longer set to "AdventureWorks". + Resetting the on a closed connection resets all connection string values (and related properties) including the password. For example, if you set a connection string that includes "Database= AdventureWorks", and then reset the connection string to "Data Source=myserver;Integrated Security=true", the property is no longer set to "AdventureWorks". The connection string is parsed immediately after being set. If errors in syntax are found when parsing, a runtime exception, such as , is generated. Other errors can be found only when an attempt is made to open the connection. @@ -1204,7 +1204,7 @@ The is similar to Keywords are not case sensitive. - The following table lists the valid names for keyword values within the . + The following table lists the valid names for keyword values within the . | Keyword | Default | Description | |--------------------|---------|----------------------------------| @@ -1332,7 +1332,7 @@ The is similar to because an attempt to connect waits indefinitely. + You can set the amount of time a connection waits to time out by using the `Connect Timeout` or `Connection Timeout` keywords in the connection string. A value of 0 indicates no limit, and should be avoided in a because an attempt to connect waits indefinitely. @@ -1462,21 +1462,21 @@ The is similar to object with . + `Persist Security Info = true` is required to get the value of the object with . - The default value of is null. + The default value of is null. An exception will be raised: -- If is set on an open connection. +- If is set on an open connection. -- If is set when `Context Connection=true`. +- If is set when `Context Connection=true`. -- If is set when `Integrated Security = true`. +- If is set when `Integrated Security = true`. -- If is set when the connection string uses `Password`. +- If is set when the connection string uses `Password`. -- If is set when the connection string uses `UserID`. +- If is set when the connection string uses `UserID`. ]]> @@ -1532,7 +1532,7 @@ The is similar to property updates dynamically. If you change the current database using a Transact-SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a Transact-SQL statement or the method, an informational message is sent and the property is updated automatically. @@ -1708,11 +1708,11 @@ The is similar to method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + You can use the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction** for this purpose. For more information, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). You can continue to enlist in an existing distributed transaction using the **EnlistDistributedTransaction** method if auto-enlistment is disabled. Enlisting in an existing distributed transaction makes sure that, if the transaction is committed or rolled back, modifications made by the code at the data source are also committed or rolled back. - `EnlistDistributedTransaction` returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), **EnlistDistributedTransaction** rolls back the local transaction and enlists in the existing distributed transaction as requested. You do not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . + `EnlistDistributedTransaction` returns an exception if the has already started a transaction using . However, if the transaction is a local transaction started at the data source (for example, by explicitly executing the BEGIN TRANSACTION statement using an object), **EnlistDistributedTransaction** rolls back the local transaction and enlists in the existing distributed transaction as requested. You do not receive notice that the local transaction was rolled back, and are responsible for managing any local transactions not started using . ]]> @@ -1750,7 +1750,7 @@ The is similar to method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). + You can use the method to enlist in a distributed transaction. Because it enlists a connection in a instance, **EnlistTransaction** takes advantage of functionality available in the namespace for managing distributed transactions, making it preferable to **EnlistDistributedTransaction**, which uses a **System.EnterpriseServices.ITransaction** object. It also has slightly different semantics: once a connection is explicitly enlisted on a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. For more information about distributed transactions, see [Distributed Transactions](/dotnet/framework/data/adonet/distributed-transactions). ]]> @@ -1791,7 +1791,7 @@ The is similar to to `true`, errors that were previously treated as exceptions are now handled as events. All events fire immediately and are handled by the event handler. If is is set to `false`, then events are handled at the end of the procedure. + When you set to `true`, errors that were previously treated as exceptions are now handled as events. All events fire immediately and are handled by the event handler. If is is set to `false`, then events are handled at the end of the procedure. > [!NOTE] > An error with a severity level of 17 or above that causes the server to stop processing the command needs to be handled as an exception. In this case, an exception is thrown regardless of how the error is handled in the event. @@ -2164,7 +2164,7 @@ class Program { An example of this is the "Tables" collection. If the "Tables" collection has three restrictions--database, owner, and table name--and you want to get back only the tables associated with the owner "Carl", you need to pass in the following values: null, "Carl". If a restriction value is not passed in, the default values are used for that restriction. This is the same mapping as passing in `null`, which is different from passing in an empty string for the parameter value. In that case, the empty string ("") is considered to be the value for the specified parameter. - For a code sample demonstrating , see . + For a code sample demonstrating , see . ]]> @@ -2269,10 +2269,10 @@ class Program { The draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to an instance of SQL Server. > [!NOTE] -> If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling . +> If the goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling . > [!NOTE] -> If you specify a port number other than 1433 when you are trying to connect to an instance of SQL Server and using a protocol other than TCP/IP, the method fails. To specify a port number other than 1433, include "server=machinename,port number" in the connection string, and use the TCP/IP protocol. +> If you specify a port number other than 1433 when you are trying to connect to an instance of SQL Server and using a protocol other than TCP/IP, the method fails. To specify a port number other than 1433, include "server=machinename,port number" in the connection string, and use the TCP/IP protocol. > [!NOTE] > The .NET Framework Data Provider for SQL Server requires the Security permission with "Allows calls to unmanaged assemblies" enabled ( with set to `UnmanagedCode`) to open a with SQL Debugging enabled. @@ -2336,9 +2336,9 @@ class Program { , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . + After calling , must return until the returned is completed. Then, if the connection was successful, must return . If the connection fails, must return . - A call to will attempt to cancel or close the corresponding call. + A call to will attempt to cancel or close the corresponding call. For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). @@ -2399,16 +2399,16 @@ class Program { ), which is sufficient for most data transfer operations. For most applications, the default packet size is best. + If an application performs bulk copy operations, or sends or receives lots of text or image data, a packet size larger than the default may improve efficiency because it causes fewer network read and write operations. If an application sends and receives small amounts of information, you can set the packet size to 512 bytes (using the Packet Size value in the ), which is sufficient for most data transfer operations. For most applications, the default packet size is best. - may be a value in the range of 512 and 32767 bytes. An exception is generated if the value is outside this range. + may be a value in the range of 512 and 32767 bytes. An exception is generated if the value is outside this range. Setting the default value to a number greater than 8000 will cause the packets to use the MultiPage allocator on the instance of SQL Server instead of the much more efficient SinglePage allocator, reducing the overall scalability of the SQL Server. For more information on how SQL Server uses memory, see [Memory Management Architecture Guide](/sql/relational-databases/memory-management-architecture-guide). ## Examples - The following example creates a , including setting the `Packet Size` to 512 in the connection string. It displays the and properties in the console window. + The following example creates a , including setting the `Packet Size` to 512 in the connection string. It displays the and properties in the console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.PacketSize Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/PacketSize/source.vb" id="Snippet1"::: @@ -2591,7 +2591,7 @@ SqlConnection.RegisterColumnEncryptionKeyStoreProviders(customKeyStoreProviders) ## Remarks The version is of the form *##.##.####*, where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The string is of the form *major.minor.build*, where major and minor are exactly two digits and build is exactly four digits. - was called while the returned Task was not completed and the connection was not opened after a call to . + was called while the returned Task was not completed and the connection was not opened after a call to . @@ -2663,7 +2663,7 @@ SqlConnection.RegisterColumnEncryptionKeyStoreProviders(customKeyStoreProviders) enumeration indicating the state of the . Closing and reopening the connection will refresh the value of . + Returns an enumeration indicating the state of the . Closing and reopening the connection will refresh the value of . ]]> diff --git a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml index 90018d55a11..93e9a25eb39 100644 --- a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -51,7 +51,7 @@ performs checks for valid key/value pairs. Therefore, you cannot use this class to create invalid connection strings; trying to add invalid pairs will throw an exception. The class maintains a fixed collection of synonyms and can translate from a synonym to the corresponding well-known key name. - For example, when you use the `Item` property to retrieve a value, you can specify a string that contains any synonym for the key you need. For example, you can specify "Network Address", "addr", or any other acceptable synonym for this key within a connection string when you use any member that requires a string that contains the key name, such as the property or the method. See the property for a full list of acceptable synonyms. + For example, when you use the `Item` property to retrieve a value, you can specify a string that contains any synonym for the key you need. For example, you can specify "Network Address", "addr", or any other acceptable synonym for this key within a connection string when you use any member that requires a string that contains the key name, such as the property or the method. See the property for a full list of acceptable synonyms. The property handles attempts to insert malicious entries. For example, the following code, using the default `Item` property (the indexer, in C#) correctly escapes the nested key/value pair: @@ -472,12 +472,12 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security method removes all key/value pairs from the , and resets all corresponding properties. This includes setting the property to 0, and setting the property to an empty string. + The method removes all key/value pairs from the , and resets all corresponding properties. This includes setting the property to 0, and setting the property to an empty string. ## Examples - The following example demonstrates calling the method. This example populates the with some key/value pairs, and then calls the method and shows the results. + The following example demonstrates calling the method. This example populates the with some key/value pairs, and then calls the method and shows the results. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.Clear/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/Clear/source.vb" id="Snippet1"::: @@ -750,7 +750,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security contains a fixed-size collection of key/value pairs, the method determines only if a particular key name is valid. + Because the contains a fixed-size collection of key/value pairs, the method determines only if a particular key name is valid. @@ -1790,12 +1790,12 @@ This property corresponds to the "Integrated Security" and "trusted_connection" ## Remarks This property corresponds to the "Password" and "pwd" keys within the connection string. - If has not been set and you retrieve the value, the return value is . To reset the password for the connection string, pass null to the Item property. + If has not been set and you retrieve the value, the return value is . To reset the password for the connection string, pass null to the Item property. ## Examples - The following example shows how to set . + The following example shows how to set . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/dataworks sqlconnectionstringbuilder.password.2/cs/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/Password/source.vb" id="Snippet1"::: @@ -1992,9 +1992,9 @@ This property corresponds to the "Integrated Security" and "trusted_connection" instance. Because the maintains a fixed-size collection of key/value pairs, calling the method simply resets the value of the key/value pair back to its default value. + Because the **Remove** method returns a value that indicates its success, it is not required to look for a key before trying to remove the key/value pair from the instance. Because the maintains a fixed-size collection of key/value pairs, calling the method simply resets the value of the key/value pair back to its default value. - Because the collection of keys supported by the is fixed, every item within the collection has a known default value. The following table lists the keys, and the value for each when the is first initialized, or after the method has been called. + Because the collection of keys supported by the is fixed, every item within the collection has a known default value. The following table lists the keys, and the value for each when the is first initialized, or after the method has been called. | Key | Default value | |--------------------------|--------------------------------| @@ -2120,7 +2120,7 @@ This property corresponds to the "Integrated Security" and "trusted_connection" method. + This method behaves identically to the method. ]]> @@ -2165,14 +2165,14 @@ This property corresponds to the "Integrated Security" and "trusted_connection" control how a binds to an enlisted . + The Transaction Binding keywords in a control how a binds to an enlisted . The following table shows the possible values for the property: |Value|Description| |-----------|-----------------| |Implicit Unbind|The default. Causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.| -|Explicit Unbind|Causes the connection to remain attached to the transaction until the connection is closed or until is called with a `null` (`Nothing` in Visual Basic) value. An is thrown if is not the enlisted transaction or if the enlisted transaction is not active. This behavior enforces the strict scoping rules required for support.| +|Explicit Unbind|Causes the connection to remain attached to the transaction until the connection is closed or until is called with a `null` (`Nothing` in Visual Basic) value. An is thrown if is not the enlisted transaction or if the enlisted transaction is not active. This behavior enforces the strict scoping rules required for support.| ]]> @@ -2337,7 +2337,7 @@ This property corresponds to the "Integrated Security" and "trusted_connection" method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because **TryGetValue** does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling **TryGetValue** with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. + The method lets developers safely retrieve a value from a without needing to verify that the supplied key name is a valid key name. Because **TryGetValue** does not raise an exception when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value. Calling **TryGetValue** with a nonexistent key will place the value null (`Nothing` in Visual Basic) in the `value` parameter. diff --git a/xml/System.Data.SqlClient/SqlDataAdapter.xml b/xml/System.Data.SqlClient/SqlDataAdapter.xml index 7ee7fd4c202..1f62c5a3e26 100644 --- a/xml/System.Data.SqlClient/SqlDataAdapter.xml +++ b/xml/System.Data.SqlClient/SqlDataAdapter.xml @@ -75,23 +75,23 @@ , serves as a bridge between a and SQL Server for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the , using the appropriate Transact-SQL statements against the data source. The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (`Insert`, `Update`, or `Delete`). Depending on the type of change, the `Insert`, `Update`, or `Delete` command template executes to propagate the modified row to the data source. When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using `FillSchema`. For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + The , serves as a bridge between a and SQL Server for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the , using the appropriate Transact-SQL statements against the data source. The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (`Insert`, `Update`, or `Delete`). Depending on the type of change, the `Insert`, `Update`, or `Delete` command template executes to propagate the modified row to the data source. When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using `FillSchema`. For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). is used in conjunction with and to increase performance when connecting to a SQL Server database. > [!NOTE] > If you are using SQL Server stored procedures to edit or delete data using a `DataAdapter`, make sure that you do not use SET NOCOUNT ON in the stored procedure definition. This causes the rows affected count returned to be zero, which the `DataAdapter` interprets as a concurrency conflict. In this event, a will be thrown. - The also includes the , , , , and properties to facilitate the loading and updating of data. + The also includes the , , , , and properties to facilitate the loading and updating of data. When an instance of is created, the read/write properties are set to initial values. For a list of these values, see the constructor. - The , , and are generic templates that are automatically filled with individual values from every modified row through the parameters mechanism. + The , , and are generic templates that are automatically filled with individual values from every modified row through the parameters mechanism. - For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The property of the object should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. + For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The property of the object should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. > [!NOTE] -> An will occur if the method is called and the table contains a user-defined type that is not available on the client computer. For more information, see [CLR User-Defined Types](/sql/relational-databases/clr-integration-database-objects-user-defined-types/clr-user-defined-types). +> An will occur if the method is called and the table contains a user-defined type that is not available on the client computer. For more information, see [CLR User-Defined Types](/sql/relational-databases/clr-integration-database-objects-user-defined-types/clr-user-defined-types). @@ -147,8 +147,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -201,12 +201,12 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. - When (or any of the other command properties) is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When (or any of the other command properties) is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. @@ -253,14 +253,14 @@ opens and closes a if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call **Close** or **Dispose** to close it. + This implementation of the opens and closes a if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call **Close** or **Dispose** to close it. When an instance of is created, the following read/write properties are set to the following initial values. |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of either of these properties through a separate call to the property. @@ -315,8 +315,8 @@ |Properties|Initial value| |----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| You can change the value of any of these properties through a separate call to the property. @@ -515,16 +515,16 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. + For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. ## Examples - The following example creates a and sets the , , , and properties. It assumes you have already created a object. + The following example creates a and sets the , , , and properties. It assumes you have already created a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: @@ -729,18 +729,18 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. If execution of this command returns rows, these rows can be added to the depending on how you set the **UpdatedRowSource** property of the object. - For every column that you propagate to the data source on , a parameter should be added to `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. + For every column that you propagate to the data source on , a parameter should be added to `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. ## Examples - The following example creates a and sets the , , , and properties. It assumes you have already created a object. + The following example creates a and sets the , , , and properties. It assumes you have already created a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: @@ -845,11 +845,11 @@ , there are two events that occur per data row updated. The order of execution is as follows: + When using , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -857,9 +857,9 @@ 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. @@ -917,11 +917,11 @@ , there are two events that occur per data row updated. The order of execution is as follows: + When using , there are two events that occur per data row updated. The order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -929,9 +929,9 @@ 5. If there are output parameters, they are placed in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. @@ -1006,14 +1006,14 @@ is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - If the does not return any rows, no tables are added to the , and no exception is raised. + If the does not return any rows, no tables are added to the , and no exception is raised. ## Examples - The following example creates a and sets the , , , and properties. It assumes you have already created a object. + The following example creates a and sets the , , , and properties. It assumes you have already created a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: @@ -1350,21 +1350,21 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. > [!NOTE] > If execution of this command returns rows, the updated rows may be merged with the depending on how you set the **UpdatedRowSource** property of the object. - For every column that you propagate to the data source on , a parameter should be added to `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. + For every column that you propagate to the data source on , a parameter should be added to `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This indicates that the value of the parameter is not set manually, but taken from the particular column in the currently processed row. ## Examples - The following example creates a and sets the , , and properties. It assumes you have already created a object. + The following example creates a and sets the , , and properties. It assumes you have already created a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.SqlClient/SqlDataReader.xml b/xml/System.Data.SqlClient/SqlDataReader.xml index 7bcb47aec6b..f14eb5f0121 100644 --- a/xml/System.Data.SqlClient/SqlDataReader.xml +++ b/xml/System.Data.SqlClient/SqlDataReader.xml @@ -58,18 +58,18 @@ , you must call the method of the object, instead of directly using a constructor. + To create a , you must call the method of the object, instead of directly using a constructor. - While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . + While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . Changes made to a result set by another process or thread while data is being read may be visible to the user of the `SqlDataReader`. However, the precise behavior is timing dependent. - and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. + and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. When using sequential access (), an will be raised if the position is advanced and another read operation is attempted on the previous column. > [!NOTE] -> For optimal performance, avoids creating unnecessary objects or making unnecessary copies of data. Therefore, multiple calls to methods such as return a reference to the same object. Use caution if you are modifying the underlying value of the objects returned by methods such as . +> For optimal performance, avoids creating unnecessary objects or making unnecessary copies of data. Therefore, multiple calls to methods such as return a reference to the same object. Use caution if you are modifying the underlying value of the objects returned by methods such as . @@ -122,9 +122,9 @@ method when you are through using the to use the associated for any other purpose. + You must explicitly call the method when you are through using the to use the associated for any other purpose. - The `Close` method fills in the values for output parameters, return values and `RecordsAffected`, increasing the time that it takes to close a `SqlDataReader` that was used to process a large or complex query. When the return values and the number of records affected by a query are not significant, the time that it takes to close the `SqlDataReader` can be reduced by calling the method of the associated object before calling the `Close` method. + The `Close` method fills in the values for output parameters, return values and `RecordsAffected`, increasing the time that it takes to close a `SqlDataReader` that was used to process a large or complex query. When the return values and the number of records affected by a query are not significant, the time that it takes to close the `SqlDataReader` can be reduced by calling the method of the associated object before calling the `Close` method. > [!CAUTION] > Do not call `Close` or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). @@ -267,7 +267,7 @@ to 0. However. this should not be confused with a query that returns 0 rows (such as SELECT * FROM *table* WHERE 1 = 2) in which case returns the number of columns in the table, including hidden fields. Use to exclude hidden fields. + Executing a query that, by its nature, does not return rows (such as a DELETE query), sets to 0. However. this should not be confused with a query that returns 0 rows (such as SELECT * FROM *table* WHERE 1 = 2) in which case returns the number of columns in the table, including hidden fields. Use to exclude hidden fields. ]]> @@ -324,7 +324,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a Boolean, or an exception is generated. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -381,7 +381,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a byte. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -444,9 +444,9 @@ returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - If you pass a buffer that is `null`, returns the length of the entire field in bytes, not the remaining size based on the buffer offset parameter. + If you pass a buffer that is `null`, returns the length of the entire field in bytes, not the remaining size based on the buffer offset parameter. No conversions are performed; therefore, the data retrieved must already be a byte array. @@ -569,14 +569,14 @@ returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - The actual number of characters read can be less than the requested length, if the end of the field is reached. If you pass a buffer that is `null`, returns the length of the entire field in characters, not the remaining size based on the buffer offset parameter. + The actual number of characters read can be less than the requested length, if the end of the field is reached. If you pass a buffer that is `null`, returns the length of the entire field in characters, not the remaining size based on the buffer offset parameter. No conversions are performed; therefore. the data retrieved must already be a character array. > [!NOTE] -> The method returns 0 when `dataIndex` is negative. +> The method returns 0 when `dataIndex` is negative. ]]> @@ -723,7 +723,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -771,7 +771,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -829,7 +829,7 @@ ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -886,7 +886,7 @@ ## Remarks No conversions are performed. Therefore, the data retrieved must already be a double-precision floating point number. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1171,7 +1171,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed. Therefore, the data retrieved must already be a single-precision floating point number. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1228,7 +1228,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a GUID. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1285,7 +1285,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a 16-bit signed integer. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1342,7 +1342,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a 32-bit signed integer. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1399,7 +1399,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a 64-bit signed integer. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -1510,7 +1510,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Examples - The following example demonstrates how to use the method. + The following example demonstrates how to use the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataReader.GetOrdinal/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataReader/GetOrdinal/source.vb" id="Snippet1"::: @@ -1676,7 +1676,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int method returns the following metadata about each column: + The method returns the following metadata about each column: |DataReader column|Description| |-----------------------|-----------------| @@ -1706,13 +1706,13 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int |NumericScale|If `ProviderType` is DBTYPE_DECIMAL or DBTYPE_NUMERIC, the number of digits to the right of the decimal point. Otherwise, this is 255.| |ProviderSpecificDataType|Returns the provider-specific data type of the column based on the `Type System Version` keyword in the connection string.| |ProviderType|The indicator of the column's data type. If the data type of the column varies from row to row, this must be Object. This column cannot contain a null value.| -|UdtAssemblyQualifiedName|If the column is a user-defined type (UDT), this is the qualified name of the UDT's assembly as per . If the column is not a UDT, this is null.| +|UdtAssemblyQualifiedName|If the column is a user-defined type (UDT), this is the qualified name of the UDT's assembly as per . If the column is not a UDT, this is null.| |XmlSchemaCollectionDatabase|The name of the database where the schema collection for this XML instance is located, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case the `XmlSchemaCollectionName` and `XmlSchemaCollectionOwningSchema` columns are also null.| |XmlSchemaCollectionName|The name of the schema collection for this XML instance, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if there is no associated schema collection. If the value is null, the `XmlSchemaCollectionDatabase` and `XmlSchemaCollectionOwningSchema` columns are also null.| |XmlSchemaCollectionOwningSchema|The owning relational schema where the schema collection for this XML instance is located, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case the `XmlSchemaCollectionDatabase` and `XmlSchemaCollectionName` columns are also null.| > [!NOTE] -> To make sure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. +> To make sure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. ]]> @@ -2516,7 +2516,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int returns data using the native SQL Server types. To retrieve data using the .NET types, see . + returns data using the native SQL Server types. To retrieve data using the .NET types, see . ]]> @@ -2618,7 +2618,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be an XML value. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -2666,15 +2666,15 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int defaults to the value of ; but you can modify via . + defaults to the value of ; but you can modify via . Null values will be returned as an empty (zero bytes) . - will raise an exception when used on an object returned by when is in effect. + will raise an exception when used on an object returned by when is in effect. exceptions raised from are thrown as exceptions; check the inner exception for the . - The following members are not available for objects returned by : + The following members are not available for objects returned by : - BeginWrite @@ -2694,7 +2694,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int - WriteTimeout - When the connection property `ContextConnection=true`, only supports synchronous data retrieval for both sequential () and non-sequential () access. + When the connection property `ContextConnection=true`, only supports synchronous data retrieval for both sequential () and non-sequential () access. For more information, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -2766,7 +2766,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a string. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -2816,9 +2816,9 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int Null values will be returned as an empty (zero bytes) . - will raise an exception when used on an object returned by when is in effect. + will raise an exception when used on an object returned by when is in effect. - When the connection property `ContextConnection=true`, only supports synchronous data retrieval for both sequential () and non-sequential () access. + When the connection property `ContextConnection=true`, only supports synchronous data retrieval for both sequential () and non-sequential () access. For more information, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -2888,7 +2888,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks No conversions are performed; therefore, the data retrieved must already be a object. - Call to check for null values before calling this method. + Call to check for null values before calling this method. ]]> @@ -2944,7 +2944,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int returns data using the .NET types. + returns data using the .NET types. ]]> @@ -3056,11 +3056,11 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int object returned by does not support asynchronous operations. If you require asynchronous operations on an , cast the XML column to an NVARCHAR(MAX) on the server and use with . + The object returned by does not support asynchronous operations. If you require asynchronous operations on an , cast the XML column to an NVARCHAR(MAX) on the server and use with . exceptions raised from are thrown as exceptions; check the inner exception for the . - will raise an exception when used on an object returned by when is in effect. + will raise an exception when used on an object returned by when is in effect. For more information, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -3257,7 +3257,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int , , and so on) to avoid raising an error. + Call this method to check for null column values before calling the typed get methods (for example, , , and so on) to avoid raising an error. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/sqldatareader_isdbnull/cs/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataReader/IsDBNull/source.vb" id="Snippet1"::: @@ -3588,9 +3588,9 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int is before the first record. Therefore, you must call to begin accessing any data. + The default position of the is before the first record. Therefore, you must call to begin accessing any data. - Only one `SqlDataReader` per associated may be open at a time, and any attempt to open another will fail until the first one is closed. Similarly, while the `SqlDataReader` is being used, the associated `SqlConnection` is busy serving it until you call . + Only one `SqlDataReader` per associated may be open at a time, and any attempt to open another will fail until the first one is closed. Similarly, while the `SqlDataReader` is being used, the associated `SqlConnection` is busy serving it until you call . @@ -3645,7 +3645,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int is set to `Default`, reads the entire row before returning the Task. + If the `behavior` parameter of is set to `Default`, reads the entire row before returning the Task. For more information, including code samples, about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). @@ -3702,7 +3702,7 @@ Boolean, Byte, Char, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int ## Remarks The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of `RecordsAffected` will be two. - and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> diff --git a/xml/System.Data.SqlClient/SqlDependency.xml b/xml/System.Data.SqlClient/SqlDependency.xml index 362aa533853..d4e62b93f4f 100644 --- a/xml/System.Data.SqlClient/SqlDependency.xml +++ b/xml/System.Data.SqlClient/SqlDependency.xml @@ -85,7 +85,7 @@ object using the default Service Broker service name and time-out. At some point after construction, you must use the method to associate one or more commands to this object. + The constructor initializes the object using the default Service Broker service name and time-out. At some point after construction, you must use the method to associate one or more commands to this object. Query notifications are supported only for SELECT statements that meet a list of specific requirements. For more information, see [SQL Server Service Broker](/sql/database-engine/configure-windows/sql-server-service-broker) and [Working with Query Notifications](/sql/connect/oledb/features/working-with-query-notifications). @@ -340,7 +340,7 @@ ## Remarks The listener will restart when an error occurs in the SQL Server connection. - Multiple calls to the method can be made, subject to the following restrictions: + Multiple calls to the method can be made, subject to the following restrictions: - Multiple calls with identical parameters (the same connection string and Windows credentials in the calling thread) are valid. @@ -393,7 +393,7 @@ ## Remarks This method starts the listener for the for receiving dependency notifications from the instance of SQL Server specified by the `connectionString` parameter. This method may be called more than once with different connection strings for multiple servers. - For additional remarks, see . + For additional remarks, see . ]]> @@ -448,7 +448,7 @@ If no queue name is specified, creates a temporary queue and service in the server that is used for the entire process, even if the process involves more than one . The queue and service are automatically removed upon application shutdown. - For additional remarks, see . + For additional remarks, see . ]]> @@ -516,7 +516,7 @@ method must be called for each call. A given listener only shuts down fully when it receives the same number of requests as requests. + The method must be called for each call. A given listener only shuts down fully when it receives the same number of requests as requests. ]]> @@ -562,7 +562,7 @@ method must be called for each call. A given listener only shuts down fully when it receives the same number of requests as requests. + The method must be called for each call. A given listener only shuts down fully when it receives the same number of requests as requests. ]]> diff --git a/xml/System.Data.SqlClient/SqlError.xml b/xml/System.Data.SqlClient/SqlError.xml index b884ccf478c..bfda4045b2f 100644 --- a/xml/System.Data.SqlClient/SqlError.xml +++ b/xml/System.Data.SqlClient/SqlError.xml @@ -41,23 +41,23 @@ Collects information relevant to a warning or error returned by SQL Server. - is created and managed by the , which in turn is created by the class. - - Messages with a severity level of 10 or less are informational and indicate problems caused by mistakes in information that a user has entered. Severity levels from 11 through 16 are generated by the user, and can be corrected by the user. Severity levels from 17 through 25 indicate software or hardware errors. When a level 17, 18, or 19 error occurs, you can continue working, although you might not be able to execute a particular statement. - - The remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server usually closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. - + is created and managed by the , which in turn is created by the class. + + Messages with a severity level of 10 or less are informational and indicate problems caused by mistakes in information that a user has entered. Severity levels from 11 through 16 are generated by the user, and can be corrected by the user. Severity levels from 17 through 25 indicate software or hardware errors. When a level 17, 18, or 19 error occurs, you can continue working, although you might not be able to execute a particular statement. + + The remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server usually closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. + For more information about errors generated by SQL Server, see [Database Engine Errors](/sql/relational-databases/errors-events/understanding-database-engine-errors). For more information about severity levels, see [Database Engine Error Severities](/sql/relational-databases/errors-events/database-engine-error-severities). - -## Examples - The following example displays each within the collection. - + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -95,21 +95,21 @@ Gets the severity level of the error returned from SQL Server. A value from 1 to 25 that indicates the severity level of the error. The default is 0. - remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server usually closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. - + remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server usually closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. + For more information on errors generated by SQL Server, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). - -## Examples - The following example displays each within the collection. - + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -145,21 +145,21 @@ Gets the line number within the Transact-SQL command batch or stored procedure that contains the error. The line number within the Transact-SQL command batch or stored procedure that contains the error. - within the collection. - + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -195,14 +195,14 @@ Gets the text describing the error. The text describing the error. For more information on errors generated by SQL Server, see Database Engine Events and Errors. - within the collection. - + within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -238,32 +238,32 @@ Gets a number that identifies the type of error. The number that identifies the type of error. -
This number corresponds to an entry in the `master.dbo.sysmessages` table.|Typically greater than 0|No| -|Connection timeout|-2|0|Yes (Number = 258)| -|Communication error (non-LocalDB)|Win32 error code|0|Yes (Number = Win32 error code)| -|Communication error (LocalDB)|Win32 error code|0|No| -|Encryption capability mismatch|20|0|No| -|Failed to start LocalDB|Win32 error code|0|No| -|Read-only routing failure|0|0|No| -|Server had severe error processing query|0|0|No| -|Processed cancellation while parsing results|0|0|No| -|Failed to create user instance|0|0|No| - +
This number corresponds to an entry in the `master.dbo.sysmessages` table.|Typically greater than 0|No| +|Connection timeout|-2|0|Yes (Number = 258)| +|Communication error (non-LocalDB)|Win32 error code|0|Yes (Number = Win32 error code)| +|Communication error (LocalDB)|Win32 error code|0|No| +|Encryption capability mismatch|20|0|No| +|Failed to start LocalDB|Win32 error code|0|No| +|Read-only routing failure|0|0|No| +|Server had severe error processing query|0|0|No| +|Processed cancellation while parsing results|0|0|No| +|Failed to create user instance|0|0|No| + For more information on errors generated by SQL Server, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). - -## Examples - The following example displays each within the collection. - + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -299,14 +299,14 @@ Gets the name of the stored procedure or remote procedure call (RPC) that generated the error. The name of the stored procedure or RPC. For more information on errors generated by SQL Server, see Database Engine Events and Errors. - within the collection. - + within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -342,14 +342,14 @@ Gets the name of the instance of SQL Server that generated the error. The name of the instance of SQL Server. - within the collection. - + within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -385,14 +385,14 @@ Gets the name of the provider that generated the error. The name of the provider that generated the error. - within the collection. - + within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -428,22 +428,22 @@ Gets the unique state code for the error. The state code. - within the collection. - + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Class/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -480,19 +480,19 @@ Some error messages can be raised at multiple points in the code for the Databas Gets the complete text of the error message. The complete text of the error. - , and the stack trace. For example: - + , and the stack trace. For example: + SqlError:UserId or Password not valid. \ - -## Examples - The following example displays each within the collection. - + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlClient/SqlException.xml b/xml/System.Data.SqlClient/SqlException.xml index 05f32b83d80..21f4f582400 100644 --- a/xml/System.Data.SqlClient/SqlException.xml +++ b/xml/System.Data.SqlClient/SqlException.xml @@ -208,7 +208,7 @@ catch (Exception ex) { . + For a code sample, see . ]]> diff --git a/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml b/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml index d48d4b1143b..d5cae229af2 100644 --- a/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml @@ -112,7 +112,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> @@ -152,7 +152,7 @@ property of the first in the collection. + This is a wrapper for the property of the first in the collection. ]]> diff --git a/xml/System.Data.SqlClient/SqlParameter.xml b/xml/System.Data.SqlClient/SqlParameter.xml index 6bb5fca2a05..487882934ff 100644 --- a/xml/System.Data.SqlClient/SqlParameter.xml +++ b/xml/System.Data.SqlClient/SqlParameter.xml @@ -180,7 +180,7 @@ are inferred from the value of the `dbType` parameter. + The data type and, if appropriate, **Size** and are inferred from the value of the `dbType` parameter. @@ -234,7 +234,7 @@ in the `value` parameter, the is inferred from the Microsoft .NET type of the . + When you specify an in the `value` parameter, the is inferred from the Microsoft .NET type of the . Use caution when you use this overload of the constructor to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero, as the following C# example demonstrates. @@ -425,7 +425,7 @@ If you do not perform this conversion, the compiler assumes that you are trying are inferred from the value of the `dbType` parameter if they are not explicitly set in the `size` and `precision` parameters. + The **Size** and are inferred from the value of the `dbType` parameter if they are not explicitly set in the `size` and `precision` parameters. @@ -496,7 +496,7 @@ If you do not perform this conversion, the compiler assumes that you are trying and are inferred from the value of the `dbType` parameter if they are not explicitly set in the `size` and `precision` parameters. + The and are inferred from the value of the `dbType` parameter if they are not explicitly set in the `size` and `precision` parameters. ]]> @@ -602,7 +602,7 @@ If you do not perform this conversion, the compiler assumes that you are trying and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -678,7 +678,7 @@ If you do not perform this conversion, the compiler assumes that you are trying ## Remarks If the is output, and execution of the associated does not return a value, the contains a null value. - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you close the . + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you close the . @@ -982,7 +982,7 @@ static void CreateSqlParameterLocaleId(){ is specified in the form @paramname. You must set before executing a that relies on parameters. + The is specified in the form @paramname. You must set before executing a that relies on parameters. @@ -1048,13 +1048,13 @@ static void CreateSqlParameterLocaleId(){ ## Remarks The property is used by parameters that have a of `Decimal`. - You do not need to specify values for the and properties for input parameters, as they can be inferred from the parameter value. `Precision` and `Scale` are required for output parameters and for scenarios where you need to specify complete metadata for a parameter without indicating a value, such as specifying a null value with a specific precision and scale. + You do not need to specify values for the and properties for input parameters, as they can be inferred from the parameter value. `Precision` and `Scale` are required for output parameters and for scenarios where you need to specify complete metadata for a parameter without indicating a value, such as specifying a null value with a specific precision and scale. > [!NOTE] > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. > [!NOTE] -> Microsoft .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data being inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. When you use .NET Framework version 1.1 or a later version, an exception is thrown if a parameter value is set with an invalid . values that exceed the parameter scale are still truncated. +> Microsoft .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data being inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. When you use .NET Framework version 1.1 or a later version, an exception is thrown if a parameter value is set with an invalid . values that exceed the parameter scale are still truncated. @@ -1104,7 +1104,7 @@ static void CreateSqlParameterLocaleId(){ and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -1147,7 +1147,7 @@ static void CreateSqlParameterLocaleId(){ and properties of the . + When executing a command that includes parameter values, code can either set the type of a parameter explicitly, or the parameter can infer its type from its value. Calling this method resets the parameter so that it can again infer its type from the value passed in the parameter. Calling this method affects both the and properties of the . ]]> @@ -1211,13 +1211,13 @@ static void CreateSqlParameterLocaleId(){ > For the `DateTime2` type, scale 0 (the default) will be passed as datetime2(7). There is currently no way to send a parameter as datetime2(0). Scales 1-7 work as expected. > This problem applies to `DateTimeOffset` and `Time` as well. - You do not need to specify values for the and properties for input parameters, as they can be inferred from the parameter value. `Precision` and `Scale` are required for output parameters and for scenarios where you need to specify complete metadata for a parameter without indicating a value, such as specifying a null value with a specific precision and scale. + You do not need to specify values for the and properties for input parameters, as they can be inferred from the parameter value. `Precision` and `Scale` are required for output parameters and for scenarios where you need to specify complete metadata for a parameter without indicating a value, such as specifying a null value with a specific precision and scale. > [!NOTE] > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. > [!NOTE] -> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. +> .NET Framework data providers that are included with the .NET Framework version 1.0 do not verify the or of parameter values. This can cause truncated data to be inserted at the data source. If you are using .NET Framework version 1.0, validate the and of values before setting the parameter value. values that exceed the parameter scale are still truncated. @@ -1287,19 +1287,19 @@ static void CreateSqlParameterLocaleId(){ ## Remarks Return values are not affected by this property; return parameters from stored procedures are always fixed-size integers. - For output parameters with a variable length type (nvarchar, for example), the size of the parameter defines the size of the buffer holding the output parameter. The output parameter can be truncated to a size specified with . For character types, the size specified with is in characters. + For output parameters with a variable length type (nvarchar, for example), the size of the parameter defines the size of the buffer holding the output parameter. The output parameter can be truncated to a size specified with . For character types, the size specified with is in characters. The property is used for binary and string types. For parameters of type `SqlType.String`, `Size` means length in Unicode characters. For parameters of type `SqlType.Xml`, `Size` is ignored. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. - For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. + For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. If not explicitly set, the size is inferred from the actual size of the specified parameter value. If the fractional part of the parameter value is greater than the size, then the value will be truncated to match the size. - For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. + For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. For information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -1369,7 +1369,7 @@ static void CreateSqlParameterLocaleId(){ is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. + When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1422,16 +1422,16 @@ static void CreateSqlParameterLocaleId(){ is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): ```tsql ((@IsNull_FieldName = 1 AND FieldName IS NULL) OR (FieldName = @Original_FieldName)) ``` - If for the field is false, generates the following WHERE clause: + If for the field is false, generates the following WHERE clause: ```tsql FieldName = @OriginalFieldName @@ -1561,7 +1561,7 @@ FieldName = @OriginalFieldName and are linked. Therefore, setting the changes the to a supporting . + The and are linked. Therefore, setting the changes the to a supporting . For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -1620,11 +1620,11 @@ FieldName = @OriginalFieldName ## Remarks For input parameters, the value is bound to the that is sent to the server. For output and return value parameters, the value is set on completion of the and after the is closed. - This property can be set to null or . Use to send a NULL value as the value of the parameter. Use null or do not set to use the default value for the parameter. + This property can be set to null or . Use to send a NULL value as the value of the parameter. Use null or do not set to use the default value for the parameter. If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - Both the and properties can be inferred by setting the . + Both the and properties can be inferred by setting the . The property is overwritten by `SqlDataAdapter.UpdateCommand`. @@ -1802,7 +1802,7 @@ FieldName = @OriginalFieldName , see [Retrieving UDT Data](/sql/relational-databases/clr-integration-database-objects-user-defined-types/accessing-user-defined-types-retrieving-udt-data). + For a sample demonstrating , see [Retrieving UDT Data](/sql/relational-databases/clr-integration-database-objects-user-defined-types/accessing-user-defined-types-retrieving-udt-data). ]]> @@ -1870,13 +1870,13 @@ FieldName = @OriginalFieldName ## Remarks For input parameters, the value is bound to the that is sent to the server. For output and return value parameters, the value is set on completion of the and after the is closed. - This property can be set to `null` or . Use to send a NULL value as the value of the parameter. Use `null` or do not set to use the default value for the parameter. + This property can be set to `null` or . Use to send a NULL value as the value of the parameter. Use `null` or do not set to use the default value for the parameter. An exception is thrown if non-Unicode XML data is passed as a string. If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - Both the and properties can be inferred by setting the Value. + Both the and properties can be inferred by setting the Value. The property is overwritten by `SqlDataAdapter.UpdateCommand`. @@ -1931,7 +1931,7 @@ FieldName = @OriginalFieldName and are also null. + This value is null (`Nothing` in Microsoft Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case and are also null. ]]> @@ -1970,7 +1970,7 @@ FieldName = @OriginalFieldName and are also null. + This value is null (`Nothing` in Microsoft Visual Basic) if there is no associated schema collection. If the value is null, then and are also null. ]]> @@ -2012,7 +2012,7 @@ FieldName = @OriginalFieldName and are also null. + This value is null (`Nothing` in Microsoft Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case and are also null. ]]> diff --git a/xml/System.Data.SqlClient/SqlParameterCollection.xml b/xml/System.Data.SqlClient/SqlParameterCollection.xml index 8bf614be7ca..d787ef673d6 100644 --- a/xml/System.Data.SqlClient/SqlParameterCollection.xml +++ b/xml/System.Data.SqlClient/SqlParameterCollection.xml @@ -564,7 +564,7 @@ parameters.Add("@pname", Convert.ToInt32(0)); replaces the `SqlParameterCollection.Add` method that takes a and an . The overload of `Add` that takes a string and an object was deprecated because of possible ambiguity with the `SqlParameterCollection.Add` overload that takes a and a enumeration value where passing an integer with the string could be interpreted as being either the parameter value or the corresponding value. Use whenever you want to add a parameter by specifying its name and value. + replaces the `SqlParameterCollection.Add` method that takes a and an . The overload of `Add` that takes a string and an object was deprecated because of possible ambiguity with the `SqlParameterCollection.Add` overload that takes a and a enumeration value where passing an integer with the string could be interpreted as being either the parameter value or the corresponding value. Use whenever you want to add a parameter by specifying its name and value. For `Xml` enumeration values, you can use a string, an XML value, an derived type instance, or a object. @@ -628,7 +628,7 @@ parameters.Add("@pname", Convert.ToInt32(0)); This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. + Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. ## Examples @@ -749,7 +749,7 @@ This member is an explicit interface member implementation. It can be used only This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. -This method uses the collection's objects' and methods on `item` to determine whether `item` exists. +This method uses the collection's objects' and methods on `item` to determine whether `item` exists. ## Examples @@ -1012,11 +1012,11 @@ This member is an explicit interface member implementation. It can be used only Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until either or is called. sets to the next element. + returns the same object until either or is called. sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. @@ -1024,7 +1024,7 @@ This member is an explicit interface member implementation. It can be used only ## Examples - The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. + The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. :::code language="csharp" source="~/snippets/csharp/System.Collections/IEnumerable/Overview/ienumerator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/IEnumerable/Overview/ienumerator.vb" id="Snippet1"::: @@ -1204,7 +1204,7 @@ This member is an explicit interface member implementation. It can be used only This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - This method uses the collection's objects' and methods on `item` to determine whether `item` exists. + This method uses the collection's objects' and methods on `item` to determine whether `item` exists. ## Examples @@ -1519,7 +1519,7 @@ This member is an explicit interface member implementation. It can be used only This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - returns an object, which can be used to synchronize access to the . + returns an object, which can be used to synchronize access to the . Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -2021,7 +2021,7 @@ This member is an explicit interface member implementation. It can be used only For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet2"::: diff --git a/xml/System.Data.SqlClient/SqlRowUpdatedEventArgs.xml b/xml/System.Data.SqlClient/SqlRowUpdatedEventArgs.xml index c5b620e2e5d..9af6114a69d 100644 --- a/xml/System.Data.SqlClient/SqlRowUpdatedEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlRowUpdatedEventArgs.xml @@ -29,43 +29,43 @@ Provides data for the event. - event is raised when an to a row is completed. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - Event Arguments: (command=System.Data.SqlClient.SqlCommand commandType=2 status=0) - - The event returns this output: - - Event Arguments: (command=System.Data.SqlClient.SqlCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) - + event is raised when an to a row is completed. + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows how to use both the and events. + + The event returns this output: + + Event Arguments: (command=System.Data.SqlClient.SqlCommand commandType=2 status=0) + + The event returns this output: + + Event Arguments: (command=System.Data.SqlClient.SqlCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.RowUpdated Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/RowUpdated/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlDataAdapter/RowUpdated/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlClient/SqlRowUpdatingEventArgs.xml b/xml/System.Data.SqlClient/SqlRowUpdatingEventArgs.xml index 90e06e2d8cc..f83aeda1f42 100644 --- a/xml/System.Data.SqlClient/SqlRowUpdatingEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlRowUpdatingEventArgs.xml @@ -29,43 +29,43 @@ Provides data for the event. - event is raised before an to a row. - - When you are using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - event args: (command=System.Data.SqlClient.SQLCommand commandType=2 status=0) - - The event returns this output: - - event args: (command=System.Data.SqlClient.SQLCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) - + event is raised before an to a row. + + When you are using , there are two events that occur for each data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows how to use both the and events. + + The event returns this output: + + event args: (command=System.Data.SqlClient.SQLCommand commandType=2 status=0) + + The event returns this output: + + event args: (command=System.Data.SqlClient.SQLCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlRowUpdatingEventArgs Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlRowUpdatingEventArgs/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlRowUpdatingEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml index 8149f1dea13..28205aeb607 100644 --- a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml @@ -108,11 +108,11 @@ property to cancel a bulk copy operation. Set to `true` to abort the bulk copy operation. + Use the property to cancel a bulk copy operation. Set to `true` to abort the bulk copy operation. If you call the **Close** method from , an exception is generated, and the object state does not change. - If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. + If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. ]]> diff --git a/xml/System.Data.SqlClient/SqlTransaction.xml b/xml/System.Data.SqlClient/SqlTransaction.xml index b20bca05f9d..f13f0aaae44 100644 --- a/xml/System.Data.SqlClient/SqlTransaction.xml +++ b/xml/System.Data.SqlClient/SqlTransaction.xml @@ -47,24 +47,24 @@ Represents a Transact-SQL transaction to be made in a SQL Server database. This class cannot be inherited. - object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. - + object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. + > [!NOTE] -> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both and generate an if the connection is terminated or if the transaction has already been rolled back on the server. - - For more information on SQL Server transactions, see [Explicit Transactions](https://msdn.microsoft.com/library/ms175127\(SQL.105\).aspx) and [Coding Efficient Transactions](https://msdn.microsoft.com/library/ms187484\(SQL.105\).aspx). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error, or if it is disposed without first being committed. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - +> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both and generate an if the connection is terminated or if the transaction has already been rolled back on the server. + + For more information on SQL Server transactions, see [Explicit Transactions](https://msdn.microsoft.com/library/ms175127\(SQL.105\).aspx) and [Coding Efficient Transactions](https://msdn.microsoft.com/library/ms187484\(SQL.105\).aspx). + + + +## Examples + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error, or if it is disposed without first being committed. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> Local Transactions @@ -109,32 +109,32 @@ Commits the database transaction. - method is equivalent to the Transact-SQL COMMIT TRANSACTION statement. You cannot roll back a transaction once it has been committed, because all modifications have become a permanent part of the database. For more information, see [COMMIT TRANSACTION (Transact-SQL) + method is equivalent to the Transact-SQL COMMIT TRANSACTION statement. You cannot roll back a transaction once it has been committed, because all modifications have become a permanent part of the database. For more information, see [COMMIT TRANSACTION (Transact-SQL) ](/sql/t-sql/language-elements/commit-transaction-transact-sql). - + > [!NOTE] -> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both `Commit` and generates an if the connection is terminated or if the transaction has already been rolled back on the server. - +> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both `Commit` and generates an if the connection is terminated or if the transaction has already been rolled back on the server. + For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - + + + +## Examples + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Local Transactions ADO.NET Overview @@ -170,11 +170,11 @@ Gets the object associated with the transaction, or if the transaction is no longer valid. The object associated with the transaction. - . - + . + ]]> Performing a Transaction @@ -273,7 +273,7 @@ Releases the unmanaged resources used and optionally releases the managed resources. . + This method calls . ]]> @@ -314,13 +314,13 @@ Specifies the for this transaction. The for this transaction. The default is . - applies to the whole transaction. - + applies to the whole transaction. + For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). - + ]]> Performing a Transaction @@ -375,34 +375,34 @@ Rolls back a transaction from a pending state. - method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [ROLLBACK TRANSACTION (Transact-SQL) + method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [ROLLBACK TRANSACTION (Transact-SQL) ](/sql/t-sql/language-elements/rollback-transaction-transact-sql). - - The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back in the event it is disposed before `Commit` or `Rollback` is called. - + + The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back in the event it is disposed before `Commit` or `Rollback` is called. + > [!NOTE] -> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. - +> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. + For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - + + + +## Examples + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Local Transactions ADO.NET Overview @@ -442,33 +442,33 @@ The name of the transaction to roll back, or the savepoint to which to roll back. Rolls back a transaction from a pending state, and specifies the transaction or savepoint name. - method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back if it is disposed before `Commit` or `Rollback` is called. - + method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). + + The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back if it is disposed before `Commit` or `Rollback` is called. + > [!NOTE] -> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. - +> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. + For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - + + + +## Examples + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/BeginTransaction/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/BeginTransaction/source1.vb" id="Snippet1"::: + ]]> No transaction name was specified. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing a Transaction ADO.NET Overview @@ -507,22 +507,22 @@ The name of the savepoint. Creates a savepoint in the transaction that can be used to roll back a part of the transaction, and specifies the savepoint name. - method is equivalent to the Transact-SQL SAVE TRANSACTION statement. - - The value used in the `savePoint` parameter can be the same value used in the `transactionName` parameter of some implementations of the method. - - Savepoints offer a mechanism to roll back parts of transactions. You create a savepoint using the method, and then later call the method to roll back to the savepoint instead of rolling back to the start of the transaction. - + method is equivalent to the Transact-SQL SAVE TRANSACTION statement. + + The value used in the `savePoint` parameter can be the same value used in the `transactionName` parameter of some implementations of the method. + + Savepoints offer a mechanism to roll back parts of transactions. You create a savepoint using the method, and then later call the method to roll back to the savepoint instead of rolling back to the start of the transaction. + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. Performing a Transaction ADO.NET Overview diff --git a/xml/System.Data.SqlTypes/SqlBinary.xml b/xml/System.Data.SqlTypes/SqlBinary.xml index 53e802945e7..b9e76543bfc 100644 --- a/xml/System.Data.SqlTypes/SqlBinary.xml +++ b/xml/System.Data.SqlTypes/SqlBinary.xml @@ -1213,7 +1213,7 @@ ## Remarks `x` will appear first in the resulting , followed by `y`. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> SQL Server Data Types and ADO.NET @@ -1268,7 +1268,7 @@ Compares two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1440,7 +1440,7 @@ Compares two structures to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1495,7 +1495,7 @@ Compares two structures to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1601,7 +1601,7 @@ Compares two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1656,7 +1656,7 @@ Compares two structures to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1711,7 +1711,7 @@ Compares two structures to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlBoolean.xml b/xml/System.Data.SqlTypes/SqlBoolean.xml index ae6972d7fd5..c23078dc222 100644 --- a/xml/System.Data.SqlTypes/SqlBoolean.xml +++ b/xml/System.Data.SqlTypes/SqlBoolean.xml @@ -83,13 +83,13 @@ Represents an integer value that is either 1 or 0 to be stored in or retrieved from a database. - structure and a standard Boolean value is that, where a standard Boolean has two possible values, `true` and `false`, a structure has three possible values, , , or . - + structure and a standard Boolean value is that, where a standard Boolean has two possible values, `true` and `false`, a structure has three possible values, , , or . + ]]> SQL Server Data Types and ADO.NET @@ -296,11 +296,11 @@ Gets the value of the structure as a byte. A byte representing the value of the structure. - SQL Server Data Types and ADO.NET @@ -314,11 +314,11 @@ Compares this instance to a specified object and returns an indication of their relative values. - interface. - + interface. + ]]> SQL Server Data Types and ADO.NET @@ -369,31 +369,31 @@ A object to compare, or a null reference ( in Visual Basic). Compares this object to the supplied object and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and value. - - Value - - Description - - A negative integer - - This instance is less than . - - Zero - - This instance is equal to . - - A positive integer - - This instance is greater than , or is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and value. + + Value + + Description + + A negative integer + + This instance is less than . + + Zero + + This instance is equal to . + + A positive integer + + This instance is greater than , or is a null reference ( in Visual Basic). + - , regardless of its value, is considered greater than a null reference (`Nothing` in Visual Basic). - + , regardless of its value, is considered greater than a null reference (`Nothing` in Visual Basic). + ]]> SQL Server Data Types and ADO.NET @@ -449,31 +449,31 @@ An object to compare, or a null reference ( in Visual Basic). Compares this structure to a specified object and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and value. - - Value - - Description - - A negative integer - - This instance is less than . - - Zero - - This instance is equal to . - - A positive integer - - This instance is greater than , or is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and value. + + Value + + Description + + A negative integer + + This instance is less than . + + Zero + + This instance is equal to . + + A positive integer + + This instance is greater than , or is a null reference ( in Visual Basic). + - , regardless of its value, is considered greater than a null reference (`Nothing` in Visual Basic). - + , regardless of its value, is considered greater than a null reference (`Nothing` in Visual Basic). + ]]> SQL Server Data Types and ADO.NET @@ -682,11 +682,11 @@ Represents a false value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> @@ -840,11 +840,11 @@ if the first instance is greater than the second instance; otherwise, . - will be null. - + will be null. + ]]> SQL Server Data Types and ADO.NET @@ -900,11 +900,11 @@ if the first instance is greater than or equal to the second instance; otherwise, . - will be null. - + will be null. + ]]> SQL Server Data Types and ADO.NET @@ -955,11 +955,11 @@ if is ; otherwise, . - is , this property still will be `false`. - + is , this property still will be `false`. + ]]> @@ -1016,11 +1016,11 @@ if the structure is null; otherwise, . - @@ -1073,11 +1073,11 @@ if is ; otherwise, . - is , this property still will be `false`. - + is , this property still will be `false`. + ]]> @@ -1136,11 +1136,11 @@ if the first instance is less than the second instance; otherwise, . - will be null. - + will be null. + ]]> SQL Server Data Types and ADO.NET @@ -1196,11 +1196,11 @@ if the first instance is less than or equal to the second instance; otherwise, . - will be null. - + will be null. + ]]> SQL Server Data Types and ADO.NET @@ -1303,11 +1303,11 @@ Represents that can be assigned to this instance of the structure. - field is a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + field is a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> @@ -1359,11 +1359,11 @@ Represents a one value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> SQL Server Data Types and ADO.NET @@ -1525,7 +1525,7 @@ Computes the bitwise OR of its operands. The results of the logical OR operation. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1581,7 +1581,7 @@ if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1636,7 +1636,7 @@ Performs a bitwise exclusive-OR (XOR) operation on the supplied parameters. The result of the logical XOR operation. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2283,12 +2283,12 @@ if the first instance is greater than the second instance; otherwise, . - will be null. - - The equivalent method for this operator is .]]> + will be null. + + The equivalent method for this operator is .]]> SQL Server Data Types and ADO.NET @@ -2343,12 +2343,12 @@ if the first instance is greater than or equal to the second instance; otherwise, . - will be null. - - The equivalent method for this operator is .]]> + will be null. + + The equivalent method for this operator is .]]> SQL Server Data Types and ADO.NET @@ -2455,7 +2455,7 @@ if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2510,12 +2510,12 @@ if the first instance is less than the second instance; otherwise, . - will be null. - - The equivalent method for this operator is .]]> + will be null. + + The equivalent method for this operator is .]]> SQL Server Data Types and ADO.NET @@ -2570,12 +2570,12 @@ if the first instance is less than or equal to the second instance; otherwise, . - will be null. - - The equivalent method for this operator is .]]> + will be null. + + The equivalent method for this operator is .]]> SQL Server Data Types and ADO.NET @@ -2679,7 +2679,7 @@ Performs a one's complement operation on the supplied structures. The one's complement of the supplied . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -3372,8 +3372,8 @@ This member is an explicit interface member implementation. It can be used only Converts this structure to . - A new structure whose value is 1 or 0. - + A new structure whose value is 1 or 0. + If the structure's value equals true, the new structure's value is 1; otherwise the new structure's value is 0. To be added. SQL Server Data Types and ADO.NET @@ -3518,11 +3518,11 @@ This member is an explicit interface member implementation. It can be used only Represents a true value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> @@ -3681,11 +3681,11 @@ This member is an explicit interface member implementation. It can be used only Represents a zero value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlByte.xml b/xml/System.Data.SqlTypes/SqlByte.xml index 7e7109820c6..c33d8c2877d 100644 --- a/xml/System.Data.SqlTypes/SqlByte.xml +++ b/xml/System.Data.SqlTypes/SqlByte.xml @@ -347,28 +347,28 @@ The object to be compared. Compares this instance to the supplied object and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -424,28 +424,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -912,11 +912,11 @@ if null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1071,11 +1071,11 @@ A constant representing the largest possible value of a . - SQL Server Data Types and ADO.NET @@ -1124,11 +1124,11 @@ A constant representing the smallest possible value of a . - SQL Server Data Types and ADO.NET @@ -1236,11 +1236,11 @@ Divides two values and returns the remainder. The remainder left after division is performed on and . - SQL Server Data Types and ADO.NET @@ -1395,11 +1395,11 @@ Represents a that can be assigned to this instance of the structure. - structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1506,7 +1506,7 @@ Computes the sum of the two specified structures. A whose property contains the sum of the two operands. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1561,7 +1561,7 @@ Computes the bitwise AND of its operands. The results of the bitwise AND operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1616,7 +1616,7 @@ Computes the bitwise OR of its two operands. The results of the bitwise OR operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1671,7 +1671,7 @@ Divides its first operand by its second. A new structure whose property contains the results of the division. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1726,7 +1726,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2374,7 +2374,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2590,7 +2590,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2700,7 +2700,7 @@ Computes the remainder after dividing its first operand by its second. A structure whose contains the remainder. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2755,7 +2755,7 @@ Computes the product of the two operands. A new structure whose property contains the product of the multiplication. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2808,7 +2808,7 @@ The ones complement operator performs a bitwise one's complement operation on its operand. A structure whose property contains the ones complement of the parameter. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3747,11 +3747,11 @@ This member is an explicit interface member implementation. It can be used only Represents a zero value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlBytes.xml b/xml/System.Data.SqlTypes/SqlBytes.xml index 50ce9100da2..c62f9015378 100644 --- a/xml/System.Data.SqlTypes/SqlBytes.xml +++ b/xml/System.Data.SqlTypes/SqlBytes.xml @@ -837,7 +837,7 @@ , an exception is thrown. + If an attempt is made to read beyond , an exception is thrown. If `count` specifies more bytes to be copied than are available from the `offset` to the end of the value, only the available bytes are copied. @@ -1405,11 +1405,11 @@ This member is an explicit interface member implementation. It can be used only but within , is updated to reflect the new ending position. + If this operation writes to a position beyond but within , is updated to reflect the new ending position. - The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. + The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. - If an attempt is made to write beyond , an exception is thrown. + If an attempt is made to write beyond , an exception is thrown. ]]> diff --git a/xml/System.Data.SqlTypes/SqlChars.xml b/xml/System.Data.SqlTypes/SqlChars.xml index 4a5340161f7..540aebae44c 100644 --- a/xml/System.Data.SqlTypes/SqlChars.xml +++ b/xml/System.Data.SqlTypes/SqlChars.xml @@ -699,7 +699,7 @@ Converts a structure to a structure. A structure. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -812,7 +812,7 @@ , an exception is thrown. + If an attempt is made to read beyond , an exception is thrown. If `count` specifies more characters to be copied than are available from the `offsetInBuffer` to the end of the value, only the available characters are copied. @@ -1327,11 +1327,11 @@ This member is an explicit interface member implementation. It can be used only but within , is updated to reflect the new ending position. + If this operation writes to a position beyond but within , is updated to reflect the new ending position. - The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. + The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. - If an attempt is made to write beyond , an exception is thrown. + If an attempt is made to write beyond , an exception is thrown. ]]> diff --git a/xml/System.Data.SqlTypes/SqlDateTime.xml b/xml/System.Data.SqlTypes/SqlDateTime.xml index 591145d9075..91a29387e6b 100644 --- a/xml/System.Data.SqlTypes/SqlDateTime.xml +++ b/xml/System.Data.SqlTypes/SqlDateTime.xml @@ -525,28 +525,28 @@ The structure to be compared. Compares this structure to the supplied structure and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than . - - Zero - - This instance is the same as . - - Greater than zero - - This instance is greater than - - -or- - - is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than . + + Zero + + This instance is the same as . + + Greater than zero + + This instance is greater than + + -or- + + is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -602,28 +602,28 @@ The to be compared. Compares this structure to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( as Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( as Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -1083,11 +1083,11 @@ if null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1242,11 +1242,11 @@ Represents the maximum valid date value for a structure. - structure is December 31, 9999. - + structure is December 31, 9999. + ]]> SQL Server Data Types and ADO.NET @@ -1295,11 +1295,11 @@ Represents the minimum valid date value for a structure. - structure is January 1, 1753. - + structure is January 1, 1753. + ]]> SQL Server Data Types and ADO.NET @@ -1401,11 +1401,11 @@ Represents a that can be assigned to this instance of the structure. - structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1515,7 +1515,7 @@ if the two values are equal. Otherwise, . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1684,7 +1684,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1739,7 +1739,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1898,7 +1898,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1953,7 +1953,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlDecimal.xml b/xml/System.Data.SqlTypes/SqlDecimal.xml index 496b30905ba..8b4a4b6dd1a 100644 --- a/xml/System.Data.SqlTypes/SqlDecimal.xml +++ b/xml/System.Data.SqlTypes/SqlDecimal.xml @@ -2123,7 +2123,7 @@ Performs a logical comparison of the two operands to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2556,7 +2556,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -3044,7 +3044,7 @@ Performs a logical comparison of two structures to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -3099,7 +3099,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -3154,7 +3154,7 @@ The multiplication operator computes the product of the two parameters. A new structure whose property contains the product of the multiplication. - .]]> + .]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlDouble.xml b/xml/System.Data.SqlTypes/SqlDouble.xml index f093ba73f1d..ff7780dbd00 100644 --- a/xml/System.Data.SqlTypes/SqlDouble.xml +++ b/xml/System.Data.SqlTypes/SqlDouble.xml @@ -241,28 +241,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -318,28 +318,28 @@ The to compare. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -395,7 +395,7 @@ The division operator divides the first operand by the second. A structure that contains the results of the division operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -808,11 +808,11 @@ if is null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -967,11 +967,11 @@ A constant representing the maximum value for a structure. - SQL Server Data Types and ADO.NET @@ -1020,11 +1020,11 @@ A constant representing the minimum possible value of . - SQL Server Data Types and ADO.NET @@ -1080,7 +1080,7 @@ The multiplication operator computes the product of the two operands. The product of the two operands. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1181,11 +1181,11 @@ Represents a that can be assigned to this instance of the structure. - structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1241,7 +1241,7 @@ The addition operator computes the sum of the two operands. The sum of the two operands. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1296,7 +1296,7 @@ The division operator divides the first operand by the second. A structure that contains the results of the division operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1352,7 +1352,7 @@ if the two values are equal. Otherwise, . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1574,7 +1574,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1629,7 +1629,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2116,7 +2116,7 @@ Compares two instances of to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2171,7 +2171,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2226,7 +2226,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2281,7 +2281,7 @@ The multiplication operator computes the product of the two operands. The product of the two operands. - ]]> + ]]> @@ -2335,7 +2335,7 @@ The subtraction operator the second operand from the first. The results of the subtraction operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3212,11 +3212,11 @@ This member is an explicit interface member implementation. It can be used only Represents a zero value that can be assigned to the property of an instance of the structure. - structure. - + structure. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlFileStream.xml b/xml/System.Data.SqlTypes/SqlFileStream.xml index e5dfef71459..655cb376eed 100644 --- a/xml/System.Data.SqlTypes/SqlFileStream.xml +++ b/xml/System.Data.SqlTypes/SqlFileStream.xml @@ -440,7 +440,7 @@ Releases the unmanaged resources used and optionally releases the managed resources. . +This method calls . ]]> diff --git a/xml/System.Data.SqlTypes/SqlGuid.xml b/xml/System.Data.SqlTypes/SqlGuid.xml index 72de144dd29..99d16dbe8b6 100644 --- a/xml/System.Data.SqlTypes/SqlGuid.xml +++ b/xml/System.Data.SqlTypes/SqlGuid.xml @@ -312,11 +312,11 @@ The next byte of the . Initializes a new instance of the structure using the specified values. - Comparing GUID and uniqueidentifier Values @@ -331,11 +331,11 @@ Compares this structure to the supplied object and returns an indication of their relative values. - Comparing GUID and uniqueidentifier Values @@ -387,28 +387,28 @@ The to be compared. Compares this structure to the supplied and returns an indication of their relative values. Compares more than the last 6 bytes, but treats the last 6 bytes as the most significant ones in comparisons. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than object. - - Zero - - This instance is the same as object. - - Greater than zero - - This instance is greater than object - - -or- - - object is a null reference (). - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than object. + + Zero + + This instance is the same as object. + + Greater than zero + + This instance is greater than object + + -or- + + object is a null reference (). + To be added. Comparing GUID and uniqueidentifier Values @@ -465,28 +465,28 @@ The to be compared. Compares this structure to the supplied object and returns an indication of their relative values. Compares more than the last 6 bytes, but treats the last 6 bytes as the most significant ones in comparisons. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than object. - - Zero - - This instance is the same as object. - - Greater than zero - - This instance is greater than object - - -or- - - object is a null reference () - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than object. + + Zero + + This instance is the same as object. + + Greater than zero + + This instance is greater than object + + -or- + + object is a null reference () + To be added. Comparing GUID and uniqueidentifier Values @@ -908,11 +908,11 @@ if . Otherwise, . - Comparing GUID and uniqueidentifier Values @@ -1124,11 +1124,11 @@ Represents a that can be assigned to this instance of the structure. - functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> Comparing GUID and uniqueidentifier Values @@ -1185,7 +1185,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET @@ -1408,7 +1408,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET @@ -1464,7 +1464,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET @@ -1572,7 +1572,7 @@ Performs a logical comparison on two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET @@ -1628,7 +1628,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET @@ -1684,7 +1684,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> Comparing GUID and uniqueidentifier Values SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlInt16.xml b/xml/System.Data.SqlTypes/SqlInt16.xml index bbfa7c5f45f..cce73f173fa 100644 --- a/xml/System.Data.SqlTypes/SqlInt16.xml +++ b/xml/System.Data.SqlTypes/SqlInt16.xml @@ -1496,7 +1496,7 @@ Computes the sum of the two operands. A structure whose property contains the sum of the two operands. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1551,7 +1551,7 @@ Computes the bitwise AND of its operands. A structure whose property contains the results of the bitwise AND. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1606,7 +1606,7 @@ Computes the bitwise OR of its two operands. A structure whose property contains the results of the bitwise OR. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1661,7 +1661,7 @@ Divides the first operand by the second. A whose property contains the results of the division. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1716,7 +1716,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1771,7 +1771,7 @@ Performs a bitwise exclusive-OR operation on the supplied parameters. A structure whose property contains the results of the bitwise XOR. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2311,7 +2311,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2366,7 +2366,7 @@ Compares two structures to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2535,7 +2535,7 @@ Performs a logical comparison of two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2590,7 +2590,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2645,7 +2645,7 @@ Compares two structures to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2700,7 +2700,7 @@ Computes the remainder after dividing its first operand by its second. A structure whose contains the remainder. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2755,7 +2755,7 @@ Computes the product of the two parameters. A structure whose contains the product of the two parameters. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2808,7 +2808,7 @@ The ~ operator performs a bitwise one's complement operation on its operand. A structure whose property contains the complement of the specified structure. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2863,7 +2863,7 @@ Subtracts the second parameter from the first. A structure whose property contains the results of the subtraction. - .]]> + .]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlInt32.xml b/xml/System.Data.SqlTypes/SqlInt32.xml index 656116d1616..6e6bff2b876 100644 --- a/xml/System.Data.SqlTypes/SqlInt32.xml +++ b/xml/System.Data.SqlTypes/SqlInt32.xml @@ -347,28 +347,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -424,28 +424,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -911,11 +911,11 @@ Indicates whether this structure is null. This property is if is null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1071,11 +1071,11 @@ A constant representing the largest possible value of a . - SQL Server Data Types and ADO.NET @@ -1124,11 +1124,11 @@ A constant representing the smallest possible value of a . - SQL Server Data Types and ADO.NET @@ -1236,11 +1236,11 @@ Divides two values and returns the remainder. The remainder left after division is performed on and . - SQL Server Data Types and ADO.NET @@ -1395,11 +1395,11 @@ Represents a that can be assigned to this instance of the class. - functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1506,7 +1506,7 @@ Computes the sum of the two specified structures. A structure whose property contains the sum of the specified structures. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1561,7 +1561,7 @@ Computes the bitwise AND of its operands. A structure that contains the results of the bitwise AND operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1616,7 +1616,7 @@ Computes the bitwise OR of the specified structures. A structure that contains the results of the bitwise OR operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1671,7 +1671,7 @@ Divides the first parameter from the second. A whose property contains the results of the division. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1726,7 +1726,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1781,7 +1781,7 @@ Performs a bitwise exclusive-OR operation on the specified structures. A structure that contains the results of the bitwise XOR operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2267,7 +2267,7 @@ Compares the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2322,7 +2322,7 @@ Compares the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2544,7 +2544,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2599,7 +2599,7 @@ Compares the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2654,7 +2654,7 @@ Compares the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2709,7 +2709,7 @@ Computes the remainder after dividing the first parameter by the second. A structure whose contains the remainder. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2764,7 +2764,7 @@ Computes the product of the two parameters. A structure whose contains the product of the two parameters. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2817,7 +2817,7 @@ Performs a bitwise one's complement operation on the specified structure. A structure that contains the results of the one's complement operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2872,7 +2872,7 @@ Subtracts the second parameter from the first. A structure whose property contains the results of the subtraction. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3808,11 +3808,11 @@ This member is an explicit interface member implementation. It can be used only Represents a zero value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlInt64.xml b/xml/System.Data.SqlTypes/SqlInt64.xml index 76818efa17f..4394344b90f 100644 --- a/xml/System.Data.SqlTypes/SqlInt64.xml +++ b/xml/System.Data.SqlTypes/SqlInt64.xml @@ -347,28 +347,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -424,28 +424,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -912,11 +912,11 @@ if null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1071,11 +1071,11 @@ A constant representing the largest possible value for a structure. - 63 -1. - + 63 -1. + ]]> SQL Server Data Types and ADO.NET @@ -1124,11 +1124,11 @@ A constant representing the smallest possible value for a structure. - 63. - + 63. + ]]> SQL Server Data Types and ADO.NET @@ -1236,11 +1236,11 @@ Divides two values and returns the remainder. The remainder left after division is performed on and . - SQL Server Data Types and ADO.NET @@ -1395,11 +1395,11 @@ Represents a that can be assigned to this instance of the structure. - functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + functions as a constant for the structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1506,7 +1506,7 @@ Computes the sum of the two parameters. A new structure whose is equal to the sum of the two parameters. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1561,7 +1561,7 @@ Computes the bitwise AND of its operands. A structure that contains the results of the bitwise AND operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1616,7 +1616,7 @@ Computes the bitwise OR of its two operands. A structure that contains the results of the bitwise OR operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1671,7 +1671,7 @@ Divides the first parameter by the second. A new structure whose property contains the results of the division operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1726,7 +1726,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1781,7 +1781,7 @@ Performs a bitwise exclusive-OR operation on the supplied parameters. A structure that contains the results of the bitwise XOR operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2203,7 +2203,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2258,7 +2258,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2527,7 +2527,7 @@ Performs a logical comparison on the two SqlInt64 parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2582,7 +2582,7 @@ Performs a logical comparison on the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2637,7 +2637,7 @@ Performs a logical comparison on the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2692,7 +2692,7 @@ Computes the remainder after dividing the first parameter by the second. A new structure whose property contains the remainder. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2747,7 +2747,7 @@ Computes the product of the two parameters. A new structure whose is equal to the product of the two parameters. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2800,7 +2800,7 @@ Performs a bitwise one's complement operation on its operand. A new structure whose is equal to the ones complement of the parameter. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2855,7 +2855,7 @@ Subtracts the second parameter from the first. A new structure whose property equals the results of the subtraction operation. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3790,11 +3790,11 @@ This member is an explicit interface member implementation. It can be used only Represents a zero value that can be assigned to the property of an instance of the structure. - field is a constant for the structure. - + field is a constant for the structure. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlMoney.xml b/xml/System.Data.SqlTypes/SqlMoney.xml index de20de71e99..b879dc3dc82 100644 --- a/xml/System.Data.SqlTypes/SqlMoney.xml +++ b/xml/System.Data.SqlTypes/SqlMoney.xml @@ -83,11 +83,11 @@ Represents a currency value ranging from -2 63 (or -922,337,203,685,477.5808) to 2 63 -1 (or +922,337,203,685,477.5807) with an accuracy to a ten-thousandth of currency unit to be stored in or retrieved from a database. - object is stored in . - + object is stored in . + ]]> SQL Server Data Types and ADO.NET @@ -399,28 +399,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -476,28 +476,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -745,11 +745,11 @@ Initializes a new instance of the class with the specified Tabular Data Stream (TDS) long value. A new structure whose property is equal to the TDS value of the parameter. - structure object directly from the Tabular Data Stream (TDS) long value passed, without making a copy of it. - + structure object directly from the Tabular Data Stream (TDS) long value passed, without making a copy of it. + ]]> @@ -1032,11 +1032,11 @@ if null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1192,11 +1192,11 @@ Represents the maximum value that can be assigned to the property of an instance of the class. - SQL Server Data Types and ADO.NET @@ -1245,11 +1245,11 @@ Represents the minimum value that can be assigned to property of an instance of the class. - SQL Server Data Types and ADO.NET @@ -1404,11 +1404,11 @@ Represents a that can be assigned to this instance of the class. - functions as a constant for the class. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + functions as a constant for the class. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -1464,7 +1464,7 @@ Calculates the sum of the two parameters. A new structure whose contains the sum of the two parameters. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1519,7 +1519,7 @@ The division operator divides the first parameter by the second. A new structure whose contains the results of the division. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -1574,7 +1574,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2009,7 +2009,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2064,7 +2064,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2444,7 +2444,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -2498,7 +2498,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2553,7 +2553,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2608,7 +2608,7 @@ The multiplication operator calculates the product of the two parameters. A new structure whose contains the product of the multiplication. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2663,7 +2663,7 @@ The subtraction operator subtracts the second parameter from the first. A new structure that contains the results of the subtraction. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3737,11 +3737,11 @@ This member is an explicit interface member implementation. It can be used only Represents the zero value that can be assigned to the property of an instance of the class. - functions as a constant for the class. - + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlNullValueException.xml b/xml/System.Data.SqlTypes/SqlNullValueException.xml index 3d206871e70..15e61abfa0e 100644 --- a/xml/System.Data.SqlTypes/SqlNullValueException.xml +++ b/xml/System.Data.SqlTypes/SqlNullValueException.xml @@ -134,8 +134,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -194,8 +194,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string specified in `message`.| +||`null`.| +||The error message string specified in `message`.| ]]> @@ -291,7 +291,7 @@ . +For more information, see . ]]> diff --git a/xml/System.Data.SqlTypes/SqlSingle.xml b/xml/System.Data.SqlTypes/SqlSingle.xml index f5fd470bc97..5f5360dd98d 100644 --- a/xml/System.Data.SqlTypes/SqlSingle.xml +++ b/xml/System.Data.SqlTypes/SqlSingle.xml @@ -1302,7 +1302,7 @@ Computes the sum of the two specified structures. A structure that contains the sum of the two specified structures. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1357,7 +1357,7 @@ Divides the first structure by the second. A structure that contains the results of the division. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1412,7 +1412,7 @@ Performs a logical comparison of the two SqlSingle parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1687,7 +1687,7 @@ Performs a logical comparison of the two operands to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -1742,7 +1742,7 @@ Performs a logical comparison of two structures to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2176,7 +2176,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2231,7 +2231,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2286,7 +2286,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2341,7 +2341,7 @@ Computes the product of the two specified structures. A structure that contains the product of the multiplication. - .]]> + .]]> SQL Server Data Types and ADO.NET @@ -2396,7 +2396,7 @@ Subtracts the second structure from the first. A structure that contains the results of the subtraction. - .]]> + .]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlString.xml b/xml/System.Data.SqlTypes/SqlString.xml index 7f1b87182b1..664ff805486 100644 --- a/xml/System.Data.SqlTypes/SqlString.xml +++ b/xml/System.Data.SqlTypes/SqlString.xml @@ -87,23 +87,23 @@ Represents a variable-length stream of characters to be stored in or retrieved from the database. has a different underlying data structure from its corresponding .NET data type. - always uses the default from the current thread, but contains its own locale Id and compare flags. The comparison result of two structures is independent of operating system and current thread locale. - - When you use comparison operators, note that if the LCIDs of arguments are different, comparison functions throw an exception because they cannot be compared. For example, the statement - -``` -SqlString mySqlString = new SqlString("abc"); -``` - - is equivalent to - -``` -SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); -``` - + always uses the default from the current thread, but contains its own locale Id and compare flags. The comparison result of two structures is independent of operating system and current thread locale. + + When you use comparison operators, note that if the LCIDs of arguments are different, comparison functions throw an exception because they cannot be compared. For example, the statement + +``` +SqlString mySqlString = new SqlString("abc"); +``` + + is equivalent to + +``` +SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); +``` + ]]> @@ -539,11 +539,11 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Concatenates two specified values to create a new structure. A that is the concatenated value of and . - , followed by `y`. - + , followed by `y`. + ]]> SQL Server Data Types and ADO.NET @@ -592,11 +592,11 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Specifies that sorts should be based on a characters numeric value instead of its alphabetical value. - functions as a constant for the class. - + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET @@ -848,28 +848,28 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic). - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic). + To be added. SQL Server Data Types and ADO.NET @@ -925,28 +925,28 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); The to be compared. Compares this object to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -1552,11 +1552,11 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Specifies that comparisons should ignore case. - functions as a constant for the class. - + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET @@ -1605,13 +1605,13 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Specifies that the string comparison must ignore the Kana type. - functions as a constant for the class. - + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET @@ -1660,13 +1660,13 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Specifies that the string comparison must ignore non-space combining characters, such as diacritics. - . - - functions as a constant for the class. - + . + + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET @@ -1715,13 +1715,13 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Specifies that the string comparison must ignore the character width. - functions as a constant for the class. - + functions as a constant for the class. + ]]> SQL Server Data Types and ADO.NET @@ -1775,11 +1775,11 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); if is . Otherwise, . - SQL Server Data Types and ADO.NET @@ -2035,11 +2035,11 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Represents a that can be assigned to this instance of the structure. - structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> SQL Server Data Types and ADO.NET @@ -2095,7 +2095,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Concatenates the two specified structures. A that contains the newly concatenated value representing the contents of the two parameters. - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2150,7 +2150,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2849,7 +2849,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -2904,7 +2904,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3010,7 +3010,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3065,7 +3065,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET @@ -3120,7 +3120,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlTruncateException.xml b/xml/System.Data.SqlTypes/SqlTruncateException.xml index f9060299eba..1e5174dd5f2 100644 --- a/xml/System.Data.SqlTypes/SqlTruncateException.xml +++ b/xml/System.Data.SqlTypes/SqlTruncateException.xml @@ -254,8 +254,8 @@ . +## Remarks +For more information, see . ]]> diff --git a/xml/System.Data.SqlTypes/SqlTypeException.xml b/xml/System.Data.SqlTypes/SqlTypeException.xml index 40b762d2c3a..e12c6fbe83d 100644 --- a/xml/System.Data.SqlTypes/SqlTypeException.xml +++ b/xml/System.Data.SqlTypes/SqlTypeException.xml @@ -225,11 +225,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -322,8 +322,8 @@ . +## Remarks +For more information, see . ]]> diff --git a/xml/System.Data.SqlTypes/SqlXml.xml b/xml/System.Data.SqlTypes/SqlXml.xml index 352d2771ed0..139ba5fb32a 100644 --- a/xml/System.Data.SqlTypes/SqlXml.xml +++ b/xml/System.Data.SqlTypes/SqlXml.xml @@ -76,11 +76,11 @@ Represents XML data stored in or retrieved from a server. - -derived type, and adds SQL-specific features such as database-style null semantics by implementing the interface. When you use SqlXml, the XML value that you assign to the SqlXml instance must be consumable by an . For unicode data, the Byte Order Mark (`BOM`) must be present in the stream of data. - + -derived type, and adds SQL-specific features such as database-style null semantics by implementing the interface. When you use SqlXml, the XML value that you assign to the SqlXml instance must be consumable by an . For unicode data, the Byte Order Mark (`BOM`) must be present in the stream of data. + ]]> Working with SQLXML @@ -233,11 +233,11 @@ An -derived class instance to be used as the value of the new instance. Creates a new instance and associates it with the content of the supplied . - returns `true`. - + returns `true`. + ]]> Working with SQLXML @@ -288,11 +288,11 @@ Gets the value of the XML content of this as a . A -derived instance that contains the XML content. The actual type may vary (for example, the return value might be ) depending on how the information is represented internally, on the server. - instance was initialized to null (`Nothing` in Visual Basic), this method returns null. - + instance was initialized to null (`Nothing` in Visual Basic), this method returns null. + ]]> Attempt was made to access this property on a null instance of . @@ -489,11 +489,11 @@ For a description of this member, see . An that describes the XML representation of the object that is produced by the method and consumed by the method. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -543,11 +543,11 @@ An XmlReader. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -597,11 +597,11 @@ The stream to which the object is serialized. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -649,11 +649,11 @@ Gets the string representation of the XML content of this instance. The string representation of the XML content. - , call the method. - + , call the method. + ]]> Working with SQLXML diff --git a/xml/System.Data/AcceptRejectRule.xml b/xml/System.Data/AcceptRejectRule.xml index 9014633c9af..77897db67b3 100644 --- a/xml/System.Data/AcceptRejectRule.xml +++ b/xml/System.Data/AcceptRejectRule.xml @@ -45,19 +45,19 @@ Determines the action that occurs when the or method is invoked on a with a . - are not final until you call the method. When either or is called on a row in the parent table, the value determines whether or not changes are propagated to corresponding rows in the child table. - - - -## Examples - The following example creates a , sets various of its properties, including the , and adds it to a object's . - + are not final until you call the method. When either or is called on a row in the parent table, the value determines whether or not changes are propagated to corresponding rows in the child table. + + + +## Examples + The following example creates a , sets various of its properties, including the , and adds it to a object's . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks Data.AcceptRejectRule/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/AcceptRejectRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/AcceptRejectRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/Constraint.xml b/xml/System.Data/Constraint.xml index ba9bbdec94d..529143455fd 100644 --- a/xml/System.Data/Constraint.xml +++ b/xml/System.Data/Constraint.xml @@ -282,7 +282,7 @@ ## Examples - The following example iterates through the of a and prints each . + The following example iterates through the of a and prints each . :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/ConstraintName/constraintname.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/Constraint/ConstraintName/source.vb" id="Snippet1"::: @@ -398,7 +398,7 @@ method to set the for a constraint. + The following example uses the method to set the for a constraint. :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/SetDataSet/setdataset.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/Constraint/SetDataSet/source.vb" id="Snippet1"::: @@ -514,7 +514,7 @@ using the method. + The following example returns the using the method. :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/ToString/tostring.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/Constraint/ToString/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/ConstraintCollection.xml b/xml/System.Data/ConstraintCollection.xml index 555bbd7d655..65942dd007f 100644 --- a/xml/System.Data/ConstraintCollection.xml +++ b/xml/System.Data/ConstraintCollection.xml @@ -86,7 +86,7 @@ > [!NOTE] > When you add a that creates a relationship between two tables to a , both a and a are created automatically. The is applied to the primary key column in the parent , and the constraint is added to that table's . The is applied to the primary key column and the foreign key column, and the constraint is added to the child table's . - The uses standard collection methods such as , , and . In addition, the method can be used to look for the existence of a particular constraint in the collection. + The uses standard collection methods such as , , and . In addition, the method can be used to look for the existence of a particular constraint in the collection. A is created when a with its property set to `true` is added to a object's . @@ -95,7 +95,7 @@ ## Examples - The first example creates a , and adds a (with its property set to `true`) to the . The second example creates a , two objects, four columns, and a . The count of constraints is then printed to show that a and a are created when a is added to the object's . + The first example creates a , and adds a (with its property set to `true`) to the . The second example creates a , two objects, four columns, and a . The count of constraints is then printed to show that a and a are created when a is added to the object's . :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Overview/constraintcollection.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Overview/source.vb" id="Snippet1"::: @@ -252,7 +252,7 @@ ## Examples - The following example uses the method to create and add a new to a . + The following example uses the method to create and add a new to a . :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source2.vb" id="Snippet1"::: @@ -563,7 +563,7 @@ has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. + If has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. @@ -625,12 +625,12 @@ is added to a , is to add a to the parent table and a to the child table. The is applied to the primary key column of the parent table, and the is applied to the foreign key column of the child table. Because trying to remove the before removing the causes an exception to be thrown, you should always use the method before calling Remove, to make sure that the can be removed. + The default behavior whenever a is added to a , is to add a to the parent table and a to the child table. The is applied to the primary key column of the parent table, and the is applied to the foreign key column of the child table. Because trying to remove the before removing the causes an exception to be thrown, you should always use the method before calling Remove, to make sure that the can be removed. ## Examples - The following example uses the method to determine whether a can be removed, before trying to remove it. + The following example uses the method to determine whether a can be removed, before trying to remove it. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.CanRemove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/CanRemove/source.vb" id="Snippet1"::: @@ -808,7 +808,7 @@ method to determine whether the specified exists before trying to remove it from the collection. You can also use the method to determine whether a can be removed. + Use the method to determine whether the specified exists before trying to remove it from the collection. You can also use the method to determine whether a can be removed. @@ -927,12 +927,12 @@ method to return an index to be used with either the or method. + Use the method to return an index to be used with either the or method. ## Examples - The following example uses the method to return the index of a . The index is passed to the method, before it is removed, to determine whether the collection contains the constraint. + The following example uses the method to return the index of a . The index is passed to the method, before it is removed, to determine whether the collection contains the constraint. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.IndexOf1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source1.vb" id="Snippet1"::: @@ -997,12 +997,12 @@ method to return an index to be used with either the or method. + Use the method to return an index to be used with either the or method. ## Examples - The following example uses the method to return the index of a . The index is passed to the method to determine whether the collection contains the constraint, before removing it. + The following example uses the method to return the index of a . The index is passed to the method to determine whether the collection contains the constraint, before removing it. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.IndexOf Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source.vb" id="Snippet1"::: @@ -1074,7 +1074,7 @@ method to test for the existence of a specific constraint. + Use the method to test for the existence of a specific constraint. @@ -1147,7 +1147,7 @@ method to test for the existence of a specific constraint. + Use the method to test for the existence of a specific constraint. @@ -1289,7 +1289,7 @@ method to determine whether the collection contains the target , and the method to determine whether a can be removed. + Before using the `Remove` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. The event occurs if the constraint is successfully removed. @@ -1354,14 +1354,14 @@ method to determine whether the collection contains the target , and the method to determine whether a can be removed. + Before using the `Remove` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. The event occurs if the constraint is successfully removed. ## Examples - The following example removes a from a after testing for its presence with the method, and whether it can be removed with the method. + The following example removes a from a after testing for its presence with the method, and whether it can be removed with the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Remove/source1.vb" id="Snippet1"::: @@ -1419,16 +1419,16 @@ method returns the index of a specific . + The method returns the index of a specific . - Before using the `RemoveAt` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. + Before using the `RemoveAt` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. The event occurs if the constraint is successfully removed. ## Examples - The following example uses the method together with the method to remove a constraint from the . + The following example uses the method together with the method to remove a constraint from the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.RemoveAt Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/RemoveAt/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DBConcurrencyException.xml b/xml/System.Data/DBConcurrencyException.xml index 5d1624e0e51..4779deb8b38 100644 --- a/xml/System.Data/DBConcurrencyException.xml +++ b/xml/System.Data/DBConcurrencyException.xml @@ -331,7 +331,7 @@ property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . ]]> @@ -385,7 +385,7 @@ property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . ]]> @@ -502,9 +502,9 @@ to retrieve the value of the row that generated the . Setting the value of the has no effect. + Use to retrieve the value of the row that generated the . Setting the value of the has no effect. - When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . Serialization support does not exist for objects. Therefore, if you serialize a object, the value of the property in the serialized version of the object is set to a null value. diff --git a/xml/System.Data/DataColumn.xml b/xml/System.Data/DataColumn.xml index 0106aea503b..febd3231aab 100644 --- a/xml/System.Data/DataColumn.xml +++ b/xml/System.Data/DataColumn.xml @@ -87,7 +87,7 @@ Each has a property that determines the kind of data the contains. For example, you can restrict the data type to integers, or strings, or decimals. Because data that is contained by the is typically merged back into its original data source, you must match the data types to those in the data source. For more information, see [Data Type Mappings in ADO.NET](/dotnet/framework/data/adonet/data-type-mappings-in-ado-net). - Properties such as , , and put restrictions on the entry and updating of data, thereby helping to guarantee data integrity. You can also use the , , and properties to control automatic data generation. For more information about columns, see [Creating AutoIncrement Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-autoincrement-columns). For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + Properties such as , , and put restrictions on the entry and updating of data, thereby helping to guarantee data integrity. You can also use the , , and properties to control automatic data generation. For more information about columns, see [Creating AutoIncrement Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-autoincrement-columns). For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). You can also make sure that values in a are unique by creating a and adding it to the of the to which the belongs. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). @@ -169,7 +169,7 @@ object has no default or . When you add it to a , a default name ("Column1", "Column2", and so on) will be generated if a name has not been assigned to the . + When created, a object has no default or . When you add it to a , a default name ("Column1", "Column2", and so on) will be generated if a name has not been assigned to the . @@ -238,7 +238,7 @@ ## Examples - The following example creates a new with a specified . + The following example creates a new with a specified . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/.ctor/source1.vb" id="Snippet1"::: @@ -313,7 +313,7 @@ with a specified and . + The following example creates a new with a specified and . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/.ctor/source2.vb" id="Snippet1"::: @@ -629,18 +629,18 @@ ## Remarks If the type of this column is not Int16, Int32, or Int64 when this property is set, the property is coerced to Int32. An exception is generated if this is a computed column. The property is set. The incremented value is used only if the row's value for this column, when added to the columns collection, is equal to the default value. - You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. + You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. - If the type of the column is or , will not work. Use Int16 or Int32 instead. + If the type of the column is or , will not work. Use Int16 or Int32 instead. - If the type of the column is or , will only partially work. Use Int64 or Decimal instead. + If the type of the column is or , will only partially work. Use Int64 or Decimal instead. - When the value is added to the current value, the overflow check is suppressed. + When the value is added to the current value, the overflow check is suppressed. ## Examples - The following example sets the , , and properties. + The following example sets the , , and properties. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/AutoIncrement/source.vb" id="Snippet1"::: @@ -709,7 +709,7 @@ , , and properties. + The following example sets the , , and properties. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/AutoIncrement/source.vb" id="Snippet1"::: @@ -776,7 +776,7 @@ , , and properties. + The following example sets the , , and properties. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/AutoIncrement/source.vb" id="Snippet1"::: @@ -993,7 +993,7 @@ property determines how a is mapped when a is saved as an XML document using the method. + The property determines how a is mapped when a is saved as an XML document using the method. For example, if a is named "customerID," and its property is set to `MappingType.Element`, the column value will produce the following XML: @@ -1019,14 +1019,14 @@ ``` - Use the constructor that contains the `type` argument to specify how the is mapped when its is transformed to an XML document. + Use the constructor that contains the `type` argument to specify how the is mapped when its is transformed to an XML document. The property corresponds to the constructor argument `type`. ## Examples - The following example sets the type property of new . + The following example sets the type property of new . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnMapping Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/ColumnMapping/source.vb" id="Snippet1"::: @@ -1093,14 +1093,14 @@ is created, it has no value. However, when the is added to a for a object, it is given a default name ("Column1", "Column2", and so on). + When a is created, it has no value. However, when the is added to a for a object, it is given a default name ("Column1", "Column2", and so on). - By default, the value is set to the value. + By default, the value is set to the value. ## Examples - The following examples gets the for every column in every table in a . The example also shows how to create a with a new . + The following examples gets the for every column in every table in a . The example also shows how to create a with a new . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnName Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/ColumnName/source.vb" id="Snippet1"::: @@ -1178,7 +1178,7 @@ value is very important for guaranteeing the correct creation and updating of data in a data source. + Setting the value is very important for guaranteeing the correct creation and updating of data in a data source. The property supports the following base .NET Framework data types: @@ -1226,10 +1226,10 @@ An exception is generated when changing this property after the column has begun storing data. - If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. + If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. > [!NOTE] -> A column of data type `Byte[]` requires special treatment in certain cases since, unlike the base .NET Framework data types, it is a reference data type. If a column of data type `Byte[]` is used as a , or as a or key for a , any change to the column value must involve assigning the `Byte[]` column value to a separately instantiated `Byte[]` object. This assignment is required to trigger the update of the internal indexes used by sorting, filtering, and primary key operations. This is illustrated by the following example: +> A column of data type `Byte[]` requires special treatment in certain cases since, unlike the base .NET Framework data types, it is a reference data type. If a column of data type `Byte[]` is used as a , or as a or key for a , any change to the column value must involve assigning the `Byte[]` column value to a separately instantiated `Byte[]` object. This assignment is required to trigger the update of the internal indexes used by sorting, filtering, and primary key operations. This is illustrated by the following example: ```csharp byte[] columnValue = (byte[])myDataTable.Rows[0][0]; @@ -1241,15 +1241,15 @@ myDataTable.Rows[0][0] = newValue; > [!NOTE] > Although it is possible to define a column as data type other than the base .NET Framework data types and `Byte[]`, such a column will be treated as a user-defined type, subject to the following usage restrictions. (For more information on user-defined types, see [Creating and Using User-Defined Types](/previous-versions/9a81d32x(v=vs.85))) -- The column cannot be part of a or expression. +- The column cannot be part of a or expression. -- If the column is used as a , or as a or for a , it must be treated as an immutable field; the column data must not be changed once it has been added to the table. +- If the column is used as a , or as a or for a , it must be treated as an immutable field; the column data must not be changed once it has been added to the table. -- Its can be only set to `MappingType.Element`. +- Its can be only set to `MappingType.Element`. - The class that implements the column's data type must be marked with the , and if necessary implement the or interface. -- Support for change tracking is limited. To utilize the class' change tracking mechanism, the class that implements the column's data type must either implement the interface, or take over the responsibility for informing the when the column value has been modified, either by calling on the row or by assigning the column value object to a separately instantiated column value object. +- Support for change tracking is limited. To utilize the class' change tracking mechanism, the class that implements the column's data type must either implement the interface, or take over the responsibility for informing the when the column value has been modified, either by calling on the row or by assigning the column value object to a separately instantiated column value object. @@ -1319,7 +1319,7 @@ myDataTable.Rows[0][0] = newValue; cannot be modified after rows are added to a , except for modifying from and or vice-versa. The modification from `UnspecifiedLocal` to `Unspecified` and vice-versa is allowed as the difference between these two options is only during serialization and does not affect the storage. + The cannot be modified after rows are added to a , except for modifying from and or vice-versa. The modification from `UnspecifiedLocal` to `Unspecified` and vice-versa is allowed as the difference between these two options is only during serialization and does not affect the storage. ]]> @@ -1381,7 +1381,7 @@ myDataTable.Rows[0][0] = newValue; ## Remarks A default value is the value that is automatically assigned to the column when a is created (for example, the date and time when the was created. - When is set to true, there can be no default value. + When is set to true, there can be no default value. You can create a new row using the property of the class and passing the method an array of values. This is a potential problem for a column with a default value because its value is generated automatically. To use the property with such a column, place `null` in the column's position in the array. For more information, see the property. @@ -1604,7 +1604,7 @@ The following example creates three columns in a . T property is ignored for non-text columns. A exception is raised if you assign to a non-string column. + The property is ignored for non-text columns. A exception is raised if you assign to a non-string column. ]]> @@ -1660,9 +1660,9 @@ The following example creates three columns in a . T property is used when reading and writing an XML document into a in the using the , , , or methods. + The property is used when reading and writing an XML document into a in the using the , , , or methods. - The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, a contains a schema read from a document that has the namespace "myCompany," and an attempt is made to read data (with the method) from a document that has the namespace "theirCompany." Any data that does not correspond to the existing schema will be ignored. + The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, a contains a schema read from a document that has the namespace "myCompany," and an attempt is made to read data (with the method) from a document that has the namespace "theirCompany." Any data that does not correspond to the existing schema will be ignored. ]]> @@ -1839,7 +1839,7 @@ The following example creates three columns in a . T is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). + The is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). ]]> diff --git a/xml/System.Data/DataColumnCollection.xml b/xml/System.Data/DataColumnCollection.xml index a5b45e13da6..0faab4a0ef4 100644 --- a/xml/System.Data/DataColumnCollection.xml +++ b/xml/System.Data/DataColumnCollection.xml @@ -81,7 +81,7 @@ ## Remarks The defines the schema of a , and determines what kind of data each can contain. You can access the through the property of the object. - The uses the and methods to insert and delete objects. Use the property to determine how many objects are in the collection. Use the method to verify whether a specified index or column name exists in the collection. + The uses the and methods to insert and delete objects. Use the property to determine how many objects are in the collection. Use the method to verify whether a specified index or column name exists in the collection. @@ -308,11 +308,11 @@ for the new column is `string`. + By default, the for the new column is `string`. If `null` or an empty string ("") is passed in for the name, a default name ("Column1", "Column2", and so on) is given to the column. - Use the method to determine whether a column with the proposed name already exists in the collection. + Use the method to determine whether a column with the proposed name already exists in the collection. If the collection is successfully changed by adding or removing columns, the event occurs. @@ -403,7 +403,7 @@ ## Remarks If `null` or an empty string ("") is passed in for the name, a default name ("Column1", "Column2", and so on) is given to the column. - Use the method to determine whether a column with the proposed name already exists in the collection. + Use the method to determine whether a column with the proposed name already exists in the collection. If the collection is successfully changed by adding or removing columns, the event occurs. @@ -502,7 +502,7 @@ ## Remarks If `null` or an empty string ("") is passed in for the name, a default name ("Column1", "Column2", and so on) is given to the column. - Use the method to determine whether a column with the proposed name already exists in the collection. + Use the method to determine whether a column with the proposed name already exists in the collection. If the collection is successfully changed by adding or removing columns, the event occurs. @@ -625,14 +625,14 @@ method performs several checks before returning a `true` or `false` result. This includes the following: whether the column exists, belongs to the table, or is involved in a constraint or relation. + The method performs several checks before returning a `true` or `false` result. This includes the following: whether the column exists, belongs to the table, or is involved in a constraint or relation. - Use the method before you try to remove any column from a collection. You can also use the method to determine whether a particular column exists before you try to remove it. + Use the method before you try to remove any column from a collection. You can also use the method to determine whether a particular column exists before you try to remove it. ## Examples - The following example first uses the method to determine whether a particular column is found in the collection. If found, the method tests whether the column can be removed. If so, the column is removed with the method. + The following example first uses the method to determine whether a particular column is found in the collection. If found, the method tests whether the column can be removed. If so, the column is removed with the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.CanRemove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/CanRemove/source.vb" id="Snippet1"::: @@ -759,7 +759,7 @@ Another column's expression depends on this column. and methods to determine whether a column exists and can be removed. + Use the and methods to determine whether a column exists and can be removed. @@ -821,12 +821,12 @@ Another column's expression depends on this column. method to confirm the existence of a column before you perform additional operations on the column. The method returns `false` when two or more columns have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a column name to exactly one column. + Use the method to confirm the existence of a column before you perform additional operations on the column. The method returns `false` when two or more columns have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a column name to exactly one column. ## Examples - The following example uses the method and the method to determine whether the column can be removed. If so, the column is removed. + The following example uses the method and the method to determine whether the column can be removed. If so, the column is removed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.Contains Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Contains/source.vb" id="Snippet1"::: @@ -946,12 +946,12 @@ Another column's expression depends on this column. method is not case-sensitive. + The method is not case-sensitive. ## Examples - The following example uses the method to determine whether a specified column exists in a . If so, the method returns the index of the column. + The following example uses the method to determine whether a specified column exists in a . If so, the method returns the index of the column. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.IndexOf Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/IndexOf/source.vb" id="Snippet1"::: @@ -1067,12 +1067,12 @@ Another column's expression depends on this column. method can be used to test for the existence of a column. This is useful before you try to use . + The method can be used to test for the existence of a column. This is useful before you try to use . ## Examples - The following example uses the property to print the value of a object specified by index. The example uses the that is contained by a System.Windows.Forms.DataGrid control. + The following example uses the property to print the value of a object specified by index. The example uses the that is contained by a System.Windows.Forms.DataGrid control. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.this Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Item/source.vb" id="Snippet1"::: @@ -1142,12 +1142,12 @@ Another column's expression depends on this column. is conditionally case-sensitive when it searches for column names. For example, if one is named "mydatacolumn" and another is named "Mydatacolumn", a string used to search for one of the columns is regarded as case-sensitive. However, if "mydatacolumn" exists and "Mydatacolumn" does not, the search string is regarded as case-insensitive. + is conditionally case-sensitive when it searches for column names. For example, if one is named "mydatacolumn" and another is named "Mydatacolumn", a string used to search for one of the columns is regarded as case-sensitive. However, if "mydatacolumn" exists and "Mydatacolumn" does not, the search string is regarded as case-insensitive. ## Examples - The following example uses the property to print the value of a object specified by index. + The following example uses the property to print the value of a object specified by index. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.this1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Item/source1.vb" id="Snippet1"::: @@ -1322,7 +1322,7 @@ Another column's expression depends on this column. ## Examples - The following example uses the method to determine whether a named column exists. If so, the property returns the column. The method then checks whether the column can be removed; if so, the method removes it. + The following example uses the method to determine whether a named column exists. If so, the property returns the column. The method then checks whether the column can be removed; if so, the method removes it. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.Remove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Remove/source.vb" id="Snippet1"::: @@ -1395,7 +1395,7 @@ Another column's expression depends on this column. ## Examples - The following example first uses the method to determine whether a particular column is found in the collection. If it is found, the method tests whether the column can be removed. If so, the column is removed with the method. + The following example first uses the method to determine whether a particular column is found in the collection. If it is found, the method tests whether the column can be removed. If so, the column is removed with the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Remove/source1.vb" id="Snippet1"::: @@ -1457,7 +1457,7 @@ Another column's expression depends on this column. ## Examples - The following example first uses the method to determine whether a particular column is found in the collection. If it is found, the method tests whether the column can be removed. If so, the column is removed with the method. + The following example first uses the method to determine whether a particular column is found in the collection. If it is found, the method tests whether the column can be removed. If so, the column is removed with the method. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/RemoveAt/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataReaderExtensions.xml b/xml/System.Data/DataReaderExtensions.xml index 3d145e252f5..2687a4f5934 100644 --- a/xml/System.Data/DataReaderExtensions.xml +++ b/xml/System.Data/DataReaderExtensions.xml @@ -574,19 +574,19 @@ Gets the value of the specified column as the requested type. The value of the specified column. To be added. - The connection was dropped or closed during data retrieval. + The connection was dropped or closed during data retrieval. -or- - - The data reader was closed during data retrieval. - + + The data reader was closed during data retrieval. + -or- - There is no data ready to be read (for example, the first hasn't been called, or it returned ). + There is no data ready to be read (for example, the first hasn't been called, or it returned ). -or- - The reader tried to read a previously-read column in sequential mode. + The reader tried to read a previously-read column in sequential mode. -or- @@ -647,7 +647,7 @@ - The connection was dropped or closed during data retrieval. - + The connection was dropped or closed during data retrieval. + -or- - The data reader was closed during the data retrieval. + The data reader was closed during the data retrieval. -or- @@ -671,7 +671,7 @@ -or- - Tried to read a previously-read column in sequential mode. + Tried to read a previously-read column in sequential mode. -or- @@ -1023,25 +1023,25 @@ Gets a stream to retrieve data from the specified column. A stream. - only supports the retrieval of values that can be converted to byte arrays. + only supports the retrieval of values that can be converted to byte arrays. ]]> - The connection was dropped or closed during the data retrieval. - + The connection was dropped or closed during the data retrieval. + -or- - The data reader is closed during the data retrieval. + The data reader is closed during the data retrieval. -or- - There is no data ready to be read (for example, the first hasn't been called, or returned false). + There is no data ready to be read (for example, the first hasn't been called, or returned false). -or- - The data reader tried to read a previously-read column in sequential mode. + The data reader tried to read a previously-read column in sequential mode. -or- @@ -1129,25 +1129,25 @@ Gets a text reader to retrieve data from the column. A text reader. - only supports the retrieval of values that can be converted to character arrays (strings). + only supports the retrieval of values that can be converted to character arrays (strings). ]]> - The connection was dropped or closed during the data retrieval. - + The connection was dropped or closed during the data retrieval. + -or- - The data reader is closed during the data retrieval. + The data reader is closed during the data retrieval. -or- - There is no data ready to be read (for example, the first hasn't been called, or returned false). + There is no data ready to be read (for example, the first hasn't been called, or returned false). -or- - The data reader tried to read a previously-read column in sequential mode. + The data reader tried to read a previously-read column in sequential mode. -or- @@ -1235,11 +1235,11 @@ if the specified column is equivalent to ; otherwise, . - , , and so on) to avoid throwing an exception. - + , , and so on) to avoid throwing an exception. + ]]> The name specified is not a valid column name. @@ -1288,7 +1288,7 @@ ## Remarks This asynchronous method is only needed to avoid blocking the calling thread when the reader is created in sequential mode. - + If sequential mode isn't specified, all column values should become available in memory each time ReadAsync completes, and calling the synchronous version of the method shouldn't block the calling thread. The default implementation of this asynchronous method invokes its synchronous counterpart and returns a completed Task, potentially blocking the calling thread. The default implementation also returns a cancelled task if passed an already cancelled cancellation token. @@ -1296,29 +1296,29 @@ Data providers that support [asynchronous programming](/dotnet/framework/data/adonet/asynchronous-programming) should override the default inmplementation using asynchronous I/O operations. This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. - + Other methods and properties of the DbDataReader object should not be invoked while the returned Task is not yet completed. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - The connection was dropped or closed during the data retrieval. - + The connection was dropped or closed during the data retrieval. + -or- - The data reader is closed during the data retrieval. + The data reader is closed during the data retrieval. -or- - There is no data ready to be read (for example, the first hasn't been called, or returned false). + There is no data ready to be read (for example, the first hasn't been called, or returned false). -or- - Trying to read a previously read column in sequential mode. + Trying to read a previously read column in sequential mode. -or- - + There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream. The name specified is not a valid column name. The cancellation token was canceled. This exception is stored into the returned task. diff --git a/xml/System.Data/DataRelation.xml b/xml/System.Data/DataRelation.xml index 8409794e9dc..5ec099f63f8 100644 --- a/xml/System.Data/DataRelation.xml +++ b/xml/System.Data/DataRelation.xml @@ -82,7 +82,7 @@ ## Remarks A is used to relate two objects to each other through objects. For example, in a Customer/Orders relationship, the Customers table is the parent and the Orders table is the child of the relationship. This is similar to a primary key/foreign key relationship. For more information, see [Navigating DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/navigating-datarelations). - Relationships are created between matching columns in the parent and child tables. That is, the value for both columns must be identical. + Relationships are created between matching columns in the parent and child tables. That is, the value for both columns must be identical. Relationships can also cascade various changes from the parent to its child rows. To control how values are changed in child rows, add a to the of the object. The determines what action to take when a value in a parent table is deleted or updated. @@ -91,7 +91,7 @@ > [!NOTE] > Data corruption can occur if a bi-directional relation is defined between two tables. A bi-directional relation consists of two `DataRelation` objects that use the same columns, with the parent-child roles switched. No exception is raised when the `DataRelation` objects are saved; however, data corruption can occur. - objects are contained in a , which you can access through the property of the , and the and properties of the . + objects are contained in a , which you can access through the property of the , and the and properties of the . @@ -500,7 +500,7 @@ object created by using this constructor must be added to the collection with the method inside of a and block. If this constructor is not called between and a will occur. In addition, the tables and columns with the specified names must exist at the time the constructor is called. + Any object created by using this constructor must be added to the collection with the method inside of a and block. If this constructor is not called between and a will occur. In addition, the tables and columns with the specified names must exist at the time the constructor is called. ]]> @@ -590,7 +590,7 @@ object created by using this constructor must then be added to the collection with . Tables and columns with the specified names must exist at the time the method is called, or if has been called before calling this constructor, the tables and columns with the specified names must exist at the time that is called. + Any object created by using this constructor must then be added to the collection with . Tables and columns with the specified names must exist at the time the method is called, or if has been called before calling this constructor, the tables and columns with the specified names must exist at the time that is called. ]]> @@ -952,7 +952,7 @@ to add custom information to a object. Add information with the Add method. Retrieve information with the Item method. + Use to add custom information to a object. Add information with the Add method. Retrieve information with the Item method. Extended properties must be of type . Properties that are not of type String are not persisted when the is written as XML. @@ -1017,7 +1017,7 @@ You can use objects to define hierarchical relationships, such as those specified in XML. For more information, see [Nesting DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/nesting-datarelations). > [!NOTE] -> If the of the child table in the relation matches the of a column in the parent table in the relation, the property must be `false`. +> If the of the child table in the relation matches the of a column in the parent table in the relation, the property must be `false`. ]]> @@ -1177,7 +1177,7 @@ of a object. + The following example gets the of a object. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentKeyConstraint/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRelationCollection.xml b/xml/System.Data/DataRelationCollection.xml index 1d3016f11ca..9209d3c9932 100644 --- a/xml/System.Data/DataRelationCollection.xml +++ b/xml/System.Data/DataRelationCollection.xml @@ -86,7 +86,7 @@ To access the collection, use the property of the object. - As soon as the collection exists you can manage the objects it contains by using methods such as , , and . + As soon as the collection exists you can manage the objects it contains by using methods such as , , and . ]]> @@ -718,7 +718,7 @@ has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. + If has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. diff --git a/xml/System.Data/DataRow.xml b/xml/System.Data/DataRow.xml index 174855c7c92..70607d69228 100644 --- a/xml/System.Data/DataRow.xml +++ b/xml/System.Data/DataRow.xml @@ -62,16 +62,16 @@ ## Remarks The and objects are primary components of a . Use the object and its properties and methods to retrieve and evaluate; and insert, delete, and update the values in the . The represents the actual objects in the , and the contains the objects that describe the schema of the . Use the overloaded property to return or set the value of a . - Use the and properties to determine the status of a particular row value, and the property to determine the state of the row relative to its parent . + Use the and properties to determine the status of a particular row value, and the property to determine the state of the row relative to its parent . - To create a new , use the method of the object. After creating a new , use the method to add the new to the . Finally, call the method of the object to confirm the addition. For more information about adding data to a , see [Adding Data to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-data-to-a-datatable). + To create a new , use the method of the object. After creating a new , use the method to add the new to the . Finally, call the method of the object to confirm the addition. For more information about adding data to a , see [Adding Data to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-data-to-a-datatable). - You can delete a from the by calling the method of the , or by calling the method of the object. The method removes the row from the collection. In contrast, marks the for removal. The actual removal occurs when you call method. By calling , you can programmatically check which rows are marked for removal before actually deleting them. For more information, see [DataRow Deletion](/dotnet/framework/data/adonet/dataset-datatable-dataview/datarow-deletion). + You can delete a from the by calling the method of the , or by calling the method of the object. The method removes the row from the collection. In contrast, marks the for removal. The actual removal occurs when you call method. By calling , you can programmatically check which rows are marked for removal before actually deleting them. For more information, see [DataRow Deletion](/dotnet/framework/data/adonet/dataset-datatable-dataview/datarow-deletion). ## Examples - The following example creates a new by calling the method of the object. + The following example creates a new by calling the method of the object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Overview/source.vb" id="Snippet1"::: @@ -178,11 +178,11 @@ , the method is implicitly called to end any edits. If the of the row was Added or Modified, the becomes Unchanged. If the was Deleted, the row is removed. + When invoking , the method is implicitly called to end any edits. If the of the row was Added or Modified, the becomes Unchanged. If the was Deleted, the row is removed. - See the method for more information. + See the method for more information. - The class also has an method, which affects changes made to the whole table. For more information and a code example that demonstrates how to accept and reject changes to individual data rows, see [AcceptChanges and RejectChanges](/dotnet/framework/data/adonet/dataset-datatable-dataview/acceptchanges-and-rejectchanges). + The class also has an method, which affects changes made to the whole table. For more information and a code example that demonstrates how to accept and reject changes to individual data rows, see [AcceptChanges and RejectChanges](/dotnet/framework/data/adonet/dataset-datatable-dataview/acceptchanges-and-rejectchanges). ## Examples The following example first creates a new with one column, and then creates a single . As the is created, added, modified, and deleted, its is printed. @@ -254,19 +254,19 @@ method to put a into edit mode. In this mode, events are temporarily suspended, letting the user make changes to more than one row without triggering validation rules. For example, if you must make sure that the value of the column for a total amount is equal to the values for the debit and credit columns in a row, you can put each row into edit mode to suspend the validation of the row values until the user tries to commit the values. + Use the method to put a into edit mode. In this mode, events are temporarily suspended, letting the user make changes to more than one row without triggering validation rules. For example, if you must make sure that the value of the column for a total amount is equal to the values for the debit and credit columns in a row, you can put each row into edit mode to suspend the validation of the row values until the user tries to commit the values. - The method is called implicitly when the user changes the value of a data-bound control; the method is called implicitly when you invoke the method for the object. While in this edit mode, the stores representations of the original and new proposed values. Therefore, as long as the method has not been called, you can retrieve either the original or proposed version by passing either `DataRowVersion.Original` or `DataRowVersion.Proposed` for the `version` parameter of the property. You can also cancel any edits at this point by invoking the method. + The method is called implicitly when the user changes the value of a data-bound control; the method is called implicitly when you invoke the method for the object. While in this edit mode, the stores representations of the original and new proposed values. Therefore, as long as the method has not been called, you can retrieve either the original or proposed version by passing either `DataRowVersion.Original` or `DataRowVersion.Proposed` for the `version` parameter of the property. You can also cancel any edits at this point by invoking the method. - To see if the row contains an original or proposed value, call the method. + To see if the row contains an original or proposed value, call the method. > [!NOTE] -> The method temporarily suspends events, but the `delete` operation does not. +> The method temporarily suspends events, but the `delete` operation does not. ## Examples - The example creates a simple with one and five objects, and a . A event handler is also added to monitor when the row's value is changing. After invoking on the existing rows, the constraint and event are temporarily disabled and the original and proposed values are printed. The is again invoked to set two rows to the same value. When is called, the is enforced on the identical values. + The example creates a simple with one and five objects, and a . A event handler is also added to monitor when the row's value is changing. After invoking on the existing rows, the constraint and event are temporarily disabled and the original and proposed values are printed. The is again invoked to set two rows to the same value. When is called, the is enforced on the identical values. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.BeginEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/BeginEdit/source.vb" id="Snippet1"::: @@ -333,12 +333,12 @@ method for more information. + See the method for more information. ## Examples - The following example edits the value of one column in the last row of a control. The example uses the , , methods to edit the column's value and commit the change to the row. + The following example edits the value of one column in the last row of a control. The example uses the , , methods to edit the column's value and commit the change to the row. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.CancelEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/CancelEdit/source.vb" id="Snippet1"::: @@ -399,16 +399,16 @@ and to set and return errors for individual columns. + Use and to set and return errors for individual columns. Set the property to set an error that applies to the whole row. - To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. ## Examples - The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. + The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.ClearErrors Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/ClearErrors/source.vb" id="Snippet1"::: @@ -467,21 +467,21 @@ of the row is Added, the becomes `Detached` and the row is removed from the table when you call . + If the of the row is Added, the becomes `Detached` and the row is removed from the table when you call . - The becomes `Deleted` after you use the method on an existing . It remains `Deleted` until you call . At this time, the is removed from the table. + The becomes `Deleted` after you use the method on an existing . It remains `Deleted` until you call . At this time, the is removed from the table. - should not be called in a foreach loop while iterating through a object. modifies the state of the collection. + should not be called in a foreach loop while iterating through a object. modifies the state of the collection. - A deleted row can be undeleted by invoking . + A deleted row can be undeleted by invoking . > [!NOTE] -> The method temporarily suspends events, but the delete operation does not. +> The method temporarily suspends events, but the delete operation does not. ## Examples - The following example creates a simple with two columns and ten rows. After deleting several items with the method, one of the rows is undeleted by invoking . + The following example creates a simple with two columns and ten rows. After deleting several items with the method, one of the rows is undeleted by invoking . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.Delete Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Delete/source.vb" id="Snippet1"::: @@ -549,7 +549,7 @@ ## Examples - The following example uses the method to end the edit of a value if the validation function returns true. + The following example uses the method to end the edit of a value if the validation function returns true. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.CancelEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/CancelEdit/source.vb" id="Snippet1"::: @@ -640,7 +640,7 @@ ## Examples - The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetChildRows2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetChildRows/source.vb" id="Snippet1"::: @@ -787,7 +787,7 @@ ## Examples - The following example uses the to return the child objects for every child in a . The value of each column with the specified version in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column with the specified version in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetChildRows3 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetChildRows/source1.vb" id="Snippet1"::: @@ -934,11 +934,11 @@ method to set column errors. + Use the method to set column errors. - To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. Alternatively, the method of the returns all rows with errors. + To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. Alternatively, the method of the returns all rows with errors. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. @@ -1008,11 +1008,11 @@ method to set column errors. + Use the method to set column errors. - To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. @@ -1082,11 +1082,11 @@ method to set column errors. + Use the method to set column errors. - To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. @@ -1152,14 +1152,14 @@ lets you reduce the number of objects that must be processed for errors by returning only those columns that have an error. Errors can be set to individual columns with the method. To further reduce the number of processing, examine the property of the class to determine whether a has errors before invoking . + The lets you reduce the number of objects that must be processed for errors by returning only those columns that have an error. Errors can be set to individual columns with the method. To further reduce the number of processing, examine the property of the class to determine whether a has errors before invoking . - Use the method to clear all errors on the row. This includes the . + Use the method to clear all errors on the row. This includes the . ## Examples - The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. + The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.ClearErrors Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/ClearErrors/source.vb" id="Snippet1"::: @@ -1232,14 +1232,14 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. ## Examples - The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetParentRow2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRow/source2.vb" id="Snippet1"::: @@ -1309,14 +1309,14 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. ## Examples - The following example uses the to print a value from each parent row of each in a . + The following example uses the to print a value from each parent row of each in a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetParentRow Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRow/source.vb" id="Snippet1"::: @@ -1378,7 +1378,7 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. @@ -1387,7 +1387,7 @@ ## Examples - The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetParentRow3 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRow/source3.vb" id="Snippet1"::: @@ -1461,7 +1461,7 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. @@ -1470,7 +1470,7 @@ ## Examples - The following example uses the to print a value from each parent row of each in a . + The following example uses the to print a value from each parent row of each in a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.GetParentRow1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRow/source1.vb" id="Snippet1"::: @@ -1548,14 +1548,14 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. ## Examples - The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRows/source.vb" id="Snippet1"::: @@ -1627,7 +1627,7 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. @@ -1694,7 +1694,7 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. @@ -1703,7 +1703,7 @@ ## Examples - The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. + The following example uses the to return the child objects for every child in a . The value of each column in the row is then printed. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/GetParentRows/source1.vb" id="Snippet1"::: @@ -1778,7 +1778,7 @@ , the collection of all parent objects for the data set is returned by the method. + In a , the collection of all parent objects for the data set is returned by the method. The also contains a collection of objects, returned by the property. @@ -1839,16 +1839,16 @@ When validating data, you can set an error on any column in a row. Such a column, when displayed in the control, is marked with a red exclamation point to signal to the user that the column is in error. - Use to set an error on any column. + Use to set an error on any column. - Use the and `GetColumnsInError` methods to return columns with errors. + Use the and `GetColumnsInError` methods to return columns with errors. - The method clears all errors for the row. + The method clears all errors for the row. ## Examples - The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. + The following example uses the to look for errors. If the row has errors, the method returns the array of columns with errors that can then be resolved. The method is then called to clear all errors. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.HasErrors Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/HasErrors/source.vb" id="Snippet1"::: @@ -1910,12 +1910,12 @@ method for more information. + See the method for more information. ## Examples - The following example uses the method to determine whether the current value of a column and the proposed value are the same. If so, the edit is canceled. Otherwise, the method is called to end the edit. + The following example uses the method to determine whether the current value of a column and the proposed value are the same. If so, the edit is canceled. Otherwise, the method is called to end the edit. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/HasVersion/source.vb" id="Snippet1"::: @@ -2048,7 +2048,7 @@ method to determine whether the value is null. + The following example changes the value of a column to a null value, and then uses the method to determine whether the value is null. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/IsNull/source.vb" id="Snippet1"::: @@ -2106,7 +2106,7 @@ method to determine whether the value is null. + The following example changes the value of a column to a null value, and then uses the method to determine whether the value is null. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/IsNull/source1.vb" id="Snippet1"::: @@ -2230,7 +2230,7 @@ ## Remarks When you set the property, an exception is generated if an exception occurs in the event. - If this is an immediate edit, see for the exceptions that can be generated. + If this is an immediate edit, see for the exceptions that can be generated. @@ -2296,7 +2296,7 @@ ## Remarks When you set the property, an exception is generated if an exception occurs in the event. - If this is an edit, see for the exceptions that can be generated. + If this is an edit, see for the exceptions that can be generated. @@ -2362,7 +2362,7 @@ ## Remarks When you set the property, an exception is generated if an exception occurs in the event. - If this is an immediate edit, see for the exceptions that can be generated. + If this is an immediate edit, see for the exceptions that can be generated. @@ -2433,7 +2433,7 @@ When you set the property, an exception is generated if an exception occurs in the event. - If this is an immediate edit, see for the exceptions that can be generated. + If this is an immediate edit, see for the exceptions that can be generated. @@ -2500,18 +2500,18 @@ method; similarly, the method must be called to commit the edit. After you call the method, and before you call the method, internal representations of the original and new proposed values are stored. Therefore, until you call the , you can use the `version` argument to specify which version of a column's value you need, either the `DataRowVersion.Original` or `DataRowVersion.Proposed`. However, as soon as you call the method, the version of the column reverts to `DataRowVersion.Original`. If the row is new, you can also pass `DataRowVersion.Default` for the parameter to retrieve the column's default value. When passing `DataRowVersion.Current`, the property returns the current value, whatever its version may be. + You can only create or update a row after you call the method; similarly, the method must be called to commit the edit. After you call the method, and before you call the method, internal representations of the original and new proposed values are stored. Therefore, until you call the , you can use the `version` argument to specify which version of a column's value you need, either the `DataRowVersion.Original` or `DataRowVersion.Proposed`. However, as soon as you call the method, the version of the column reverts to `DataRowVersion.Original`. If the row is new, you can also pass `DataRowVersion.Default` for the parameter to retrieve the column's default value. When passing `DataRowVersion.Current`, the property returns the current value, whatever its version may be. > [!NOTE] -> The method is called implicitly when you change the value of a data-bound control or when a object is added to the ; the method is called implicitly when you call the following methods: the method of the object, the method of the object, or the method. +> The method is called implicitly when you change the value of a data-bound control or when a object is added to the ; the method is called implicitly when you call the following methods: the method of the object, the method of the object, or the method. - By contrast, the enumeration `Current` returns the version of the data after the method has been called. + By contrast, the enumeration `Current` returns the version of the data after the method has been called. The `version` argument should not be confused with the property. The `version` argument describes the state of the data that is contained by the column relative to the column's original value. The property describes the state of the whole row relative to its parent . When you set the property, an exception is generated if an exception occurs in the event. - If this is an immediate edit, see for the exceptions that can be generated. + If this is an immediate edit, see for the exceptions that can be generated. @@ -2581,7 +2581,7 @@ When you set the property, an exception is generated if an exception occurs in the event. - If this is an immediate edit, see for the exceptions that can be generated. + If this is an immediate edit, see for the exceptions that can be generated. @@ -2650,7 +2650,7 @@ indicates that no value was specified. + You can use this property to set or get values for this row through an array. If you use this property to set values, the array must have the same size and ordering as the column collection. Passing `null` in the indicates that no value was specified. Users can generate exceptions in the event or the event. @@ -2718,12 +2718,12 @@ method, the method is implicitly called to cancel any edits. If is deleted or modified, the row reverts to its previous values, and becomes unchanged. If the is added, the row is removed. + When you call the method, the method is implicitly called to cancel any edits. If is deleted or modified, the row reverts to its previous values, and becomes unchanged. If the is added, the row is removed. ## Examples - The following example creates a simple with 2 columns and 10 rows. After several items are deleted with the method, one of the rows is undeleted by invoking . + The following example creates a simple with 2 columns and 10 rows. After several items are deleted with the method, one of the rows is undeleted by invoking . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.Delete Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Delete/source.vb" id="Snippet1"::: @@ -2837,7 +2837,7 @@ depends on two factors: the kind of operation has been performed on the row, and whether has been called on the . + The value of the depends on two factors: the kind of operation has been performed on the row, and whether has been called on the . @@ -2978,17 +2978,17 @@ method. + To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. To set a custom error description on the whole row, use the property. - To determine whether any errors exist for the columns collection, use the method. + To determine whether any errors exist for the columns collection, use the method. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. @@ -3060,15 +3060,15 @@ ## Remarks The method is used to set custom error descriptions on specified columns. You can use the control to display the text of the error. - To examine error descriptions, use the method. + To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. To set a custom error description on the whole row, use the property. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. To set error text that applies to a whole row, set the property. @@ -3150,17 +3150,17 @@ ## Remarks The name of a column is set with the property of the class. - To examine error descriptions, use the method. + To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. To set a custom error description on the whole row, use the property. - To determine whether any errors exist for the columns collection, use the method. + To determine whether any errors exist for the columns collection, use the method. - To clear all errors for the columns collection, use the method. + To clear all errors for the columns collection, use the method. @@ -3277,7 +3277,7 @@ method to determine whether a column contains a null value. + Use the method to determine whether a column contains a null value. ]]> diff --git a/xml/System.Data/DataRowChangeEventArgs.xml b/xml/System.Data/DataRowChangeEventArgs.xml index 93e0bd5820f..268847c3c70 100644 --- a/xml/System.Data/DataRowChangeEventArgs.xml +++ b/xml/System.Data/DataRowChangeEventArgs.xml @@ -52,18 +52,18 @@ Provides data for the , , , and events. - , , , and events occur when an action is performed on a . - - - -## Examples - The following example adds a and the procedure to handle the event when a row is changed. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: - + , , , and events occur when an action is performed on a . + + + +## Examples + The following example adds a and the procedure to handle the event when a row is changed. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> @@ -118,13 +118,13 @@ One of the values. Initializes a new instance of the class. - and the procedure to handle the event when a row is changed. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: - + and the procedure to handle the event when a row is changed. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> @@ -177,13 +177,13 @@ Gets the action that has occurred on a . One of the values. - and the procedure to handle the event when a row is changed. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: - + and the procedure to handle the event when a row is changed. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> @@ -236,13 +236,13 @@ Gets the row upon which an action has occurred. The upon which an action has occurred. - and the procedure to handle the event when a row is changed. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: - + and the procedure to handle the event when a row is changed. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowChangeEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/DataRowCollection.xml b/xml/System.Data/DataRowCollection.xml index c6e83cf0c8e..3744bda55ef 100644 --- a/xml/System.Data/DataRowCollection.xml +++ b/xml/System.Data/DataRowCollection.xml @@ -65,14 +65,14 @@ ## Remarks The is a major component of the . While the defines the schema of the table, the contains the actual data for the table, where each in the represents a single row. - You can call the and methods to insert and delete objects from the . You can also call the method to search for objects that contain specific values in primary key columns, and the method to search character-based data for single words or phrases. + You can call the and methods to insert and delete objects from the . You can also call the method to search for objects that contain specific values in primary key columns, and the method to search character-based data for single words or phrases. For other operations, such as sorting or filtering the , use methods on the 's associated . ## Examples - The first example in this section prints the value of column 1 for every row in a . The second example adds a new row created by using the method to the . + The first example in this section prints the value of column 1 for every row in a . The second example adds a new row created by using the method to the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source.vb" id="Snippet1"::: @@ -141,14 +141,14 @@ , you must use the method of the class. When you use the method, a new object is returned using the schema of parent . After you create the object and set the values for each of its columns, use the method to add the object to the collection. + To create a new , you must use the method of the class. When you use the method, a new object is returned using the schema of parent . After you create the object and set the values for each of its columns, use the method to add the object to the collection. Generates an exception if the user generates an exception in the event. If an exception occurs, the row is not added to the table. ## Examples - The following example uses the method to add a new to a object. + The following example uses the method to add a new to a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Add Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Overview/source.vb" id="Snippet1"::: @@ -230,14 +230,14 @@ object has its set to True, null should be passed to get the default value for that column. + If a object has its set to True, null should be passed to get the default value for that column. Exceptions can also occur if you generate an exception during either a or event. If an exception occurs, the row is not added to the table. ## Examples - The following example uses the method to create and add a new object to a . + The following example uses the method to create and add a new object to a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Add1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source1.vb" id="Snippet1"::: @@ -359,14 +359,14 @@ method, the object to which the object belongs to must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. + To use the method, the object to which the object belongs to must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. - As soon as you have determined that a row contains the specified value, you can use the method to return the specific object that has the value. + As soon as you have determined that a row contains the specified value, you can use the method to return the specific object that has the value. ## Examples - The following Visual Basic example uses the method to determine whether a object contains a specific value. + The following Visual Basic example uses the method to determine whether a object contains a specific value. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source.vb" id="Snippet1"::: @@ -433,14 +433,14 @@ method with an array of values, the object to which the object belongs must have an array of columns designated as primary keys. See the property for more information about how to create an array of primary key columns. The number of array elements must correspond to the number of primary key columns in the . + To use the method with an array of values, the object to which the object belongs must have an array of columns designated as primary keys. See the property for more information about how to create an array of primary key columns. The number of array elements must correspond to the number of primary key columns in the . - As soon as you have determined that a row contains the specified value, use the method to return the specific object that has the value. + As soon as you have determined that a row contains the specified value, use the method to return the specific object that has the value. ## Examples - The following Visual Basic example uses the method to find a particular row in a object. The example creates an array of values, one element for each primary key in the table, and then passes the array to the method to return a `true` or `false`. + The following Visual Basic example uses the method to find a particular row in a object. The example creates an array of values, one element for each primary key in the table, and then passes the array to the method to return a `true` or `false`. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source1.vb" id="Snippet1"::: @@ -658,7 +658,7 @@ ## Examples - The following example uses the method to find the primary key value "2" in a collection of objects. The method returns the specific object letting you change its values, as needed. + The following example uses the method to find the primary key value "2" in a collection of objects. The method returns the specific object letting you change its values, as needed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Find Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source.vb" id="Snippet1"::: @@ -726,12 +726,12 @@ method, the object to which the object belongs must have at least one column designated as a primary key column. When two or more rows have the same primary key value, then the first row found is returned. This occurs when is set to false. See the property for more information about how to create a column, or an array of objects when the table has more than one primary key. + To use the method, the object to which the object belongs must have at least one column designated as a primary key column. When two or more rows have the same primary key value, then the first row found is returned. This occurs when is set to false. See the property for more information about how to create a column, or an array of objects when the table has more than one primary key. ## Examples - The following example uses the values of an array to find a specific row in a collection of objects. The method assumes that a exists with three primary key columns. After creating an array of the values, the code uses the method with the array to get the particular object that you want. + The following example uses the values of an array to find a specific row in a collection of objects. The method assumes that a exists with three primary key columns. After creating an array of the values, the code uses the method with the array to get the particular object that you want. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Find1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source1.vb" id="Snippet1"::: @@ -881,7 +881,7 @@ is reflected by the order of rows in the only. If more than one row is returned in a array, the inserted row may not be returned in the location specified by . For example, the property returns the row in the specified insert position. and may not. When you write the contents of the as XML, for example, , the rows are written according to the order specified by the . + The location specified by is reflected by the order of rows in the only. If more than one row is returned in a array, the inserted row may not be returned in the location specified by . For example, the property returns the row in the specified insert position. and may not. When you write the contents of the as XML, for example, , the rows are written according to the order specified by the . If the value specified for the `pos` parameter is greater than the number of rows in the collection, the new row is added to the end. @@ -937,7 +937,7 @@ method to determine whether a specific value exists in the key column of a row. + Use the method to determine whether a specific value exists in the key column of a row. @@ -1026,16 +1026,16 @@ method of the class to just mark a row for removal. Calling `Remove` is the same as calling and then calling . + When a row is removed, all data in that row is lost. You can also call the method of the class to just mark a row for removal. Calling `Remove` is the same as calling and then calling . - should not be called in a foreach loop while iterating through a object. modifies the state of the collection. + should not be called in a foreach loop while iterating through a object. modifies the state of the collection. - You can also use the method to remove all members of the collection at one time. + You can also use the method to remove all members of the collection at one time. ## Examples - The following example uses the method to delete a found row in a object. The example first uses the method to determine whether the rows collection contains a row. If it does, the method is used to find the specific row, and the method is then used to remove the row. + The following example uses the method to delete a found row in a object. The example first uses the method to determine whether the rows collection contains a row. If it does, the method is used to find the specific row, and the method is then used to remove the row. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Remove/source.vb" id="Snippet1"::: @@ -1093,14 +1093,14 @@ method of the class to just mark a row for removal. Calling `RemoveAt` is the same as calling and then calling . + When a row is removed, all data in that row is lost. You can also call the method of the class to just mark a row for removal. Calling `RemoveAt` is the same as calling and then calling . - You can use the method to remove all members of the collection at one time. + You can use the method to remove all members of the collection at one time. ## Examples - The following example removes the last row in a by calling the method. + The following example removes the last row in a by calling the method. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/RemoveAt/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRowComparer.xml b/xml/System.Data/DataRowComparer.xml index 215e93f0ffb..d2eafb0f96e 100644 --- a/xml/System.Data/DataRowComparer.xml +++ b/xml/System.Data/DataRowComparer.xml @@ -60,9 +60,9 @@ class is used to compare the values of the objects and does not compare the object references. + The class is used to compare the values of the objects and does not compare the object references. - This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. + This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. This class is stateless. diff --git a/xml/System.Data/DataRowComparer`1.xml b/xml/System.Data/DataRowComparer`1.xml index 24de3891a22..4b6b1ece76e 100644 --- a/xml/System.Data/DataRowComparer`1.xml +++ b/xml/System.Data/DataRowComparer`1.xml @@ -78,9 +78,9 @@ interface and uses value-based semantics to compare objects. This class is required because the default implementations of some set-based operations (such as , , , and ) use reference-based semantics to compare object references, instead of comparing the object values. The class is used to compare the values of the objects and does not compare the object references. + This class implements the interface and uses value-based semantics to compare objects. This class is required because the default implementations of some set-based operations (such as , , , and ) use reference-based semantics to compare object references, instead of comparing the object values. The class is used to compare the values of the objects and does not compare the object references. - This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. + This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. This class is stateless. @@ -199,7 +199,7 @@ Only the current values of the objects are checked. The state of the objects is not checked. - The method is the value-based comparison implementation of the method. + The method is the value-based comparison implementation of the method. ]]> @@ -254,7 +254,7 @@ method is the value-based comparison implementation of the method. + The method is the value-based comparison implementation of the method. ]]> diff --git a/xml/System.Data/DataRowExtensions.xml b/xml/System.Data/DataRowExtensions.xml index 24932385efa..ec187f6cfd1 100644 --- a/xml/System.Data/DataRowExtensions.xml +++ b/xml/System.Data/DataRowExtensions.xml @@ -60,7 +60,7 @@ API has been extended with two new methods of the class, and . You can use these to form Language-Integrated Query (LINQ) expressions and method queries against objects. They are the recommended methods to use for accessing column values within Language-Integrated Query (LINQ) expressions and method queries. For more information, see [Generic Field and SetField Methods](/dotnet/framework/data/adonet/generic-field-and-setfield-methods-linq-to-dataset). + The API has been extended with two new methods of the class, and . You can use these to form Language-Integrated Query (LINQ) expressions and method queries against objects. They are the recommended methods to use for accessing column values within Language-Integrated Query (LINQ) expressions and method queries. For more information, see [Generic Field and SetField Methods](/dotnet/framework/data/adonet/generic-field-and-setfield-methods-linq-to-dataset). ]]> @@ -138,11 +138,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, and do not support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, and do not support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is and `T` is a reference type or nullable type, the return type will be **null**. The method will not return . + If the value of the specified is and `T` is a reference type or nullable type, the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -208,11 +208,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is **null** and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . + If the value of the specified is **null** and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -284,11 +284,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, and do not support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, and do not support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is **null** and `T` is a reference type or nullable type, the return type will be **null**. The method will not return . + If the value of the specified is **null** and `T` is a reference type or nullable type, the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -362,11 +362,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . + If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -434,11 +434,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . + If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -512,11 +512,11 @@ class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. + The class represents **null** values with the instance of the class. A Language-Integrated Query (LINQ) expression that accessed a column with a **null** value would generate a at run time. Additionally, doesn't support nullable types. The method provides support for accessing columns as nullable types. If the underlying value in the is , the returned nullable type will have a value of **null**. - If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . + If the value of the specified is null and `T` is a reference type or nullable type, then the return type will be **null**. The method will not return . - The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. + The method does not perform type conversions. If type conversion is required, you should first obtain the column value by using the method. The column value should then be converted to another type. ]]> @@ -599,11 +599,11 @@ method converts the **null** value to in the underlying . + If `value` is **null**, the method converts the **null** value to in the underlying . - The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. + The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. - Exceptions can be passed up through the method from the underlying object. + Exceptions can be passed up through the method from the underlying object. ]]> @@ -671,11 +671,11 @@ method converts the **null** value to in the underlying . + If `value` is **null**, the method converts the **null** value to in the underlying . - The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. + The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. - Exceptions can be passed up through the method from the underlying object. + Exceptions can be passed up through the method from the underlying object. ]]> @@ -749,11 +749,11 @@ method converts the **null** value to in the underlying . + If `value` is **null**, the method converts the **null** value to in the underlying . - The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. + The method does not perform any type conversions. This does not mean, however, that a type conversion will not occur. The method exposes the ADO.NET 2.0 behavior of the class. A type conversion could be performed by the object and the converted value would then be saved to the row. - Exceptions can be passed up through the method from the underlying object. + Exceptions can be passed up through the method from the underlying object. ]]> diff --git a/xml/System.Data/DataRowState.xml b/xml/System.Data/DataRowState.xml index 750a78dde12..41766ef014c 100644 --- a/xml/System.Data/DataRowState.xml +++ b/xml/System.Data/DataRowState.xml @@ -59,7 +59,7 @@ ## Examples - The following example first creates a new with one column, then creates a single . As the is created, added, modified, and deleted, its is printed. + The following example first creates a new with one column, then creates a single . As the is created, added, modified, and deleted, its is printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowState Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowState/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRowVersion.xml b/xml/System.Data/DataRowVersion.xml index 7ffb4fb47a8..65512d6a687 100644 --- a/xml/System.Data/DataRowVersion.xml +++ b/xml/System.Data/DataRowVersion.xml @@ -49,26 +49,26 @@ values are used when retrieving the value found in a using or the of the object. + The values are used when retrieving the value found in a using or the of the object. The informs you what version of a exists. Versions change under the following circumstances: -- After calling the object's method, if you change the value, the `Current` and `Proposed` values become available. +- After calling the object's method, if you change the value, the `Current` and `Proposed` values become available. -- After calling the object's method, the `Proposed` value is deleted. +- After calling the object's method, the `Proposed` value is deleted. -- After calling the object's method, the Proposed value becomes the `Current` value. +- After calling the object's method, the Proposed value becomes the `Current` value. -- After calling the object's method, the `Original` value becomes identical to the `Current` value. +- After calling the object's method, the `Original` value becomes identical to the `Current` value. -- After calling the object's method, the `Original` value becomes identical to the `Current` value. +- After calling the object's method, the `Original` value becomes identical to the `Current` value. -- After calling the object's method, the `Proposed` value is discarded, and the version becomes `Current`. +- After calling the object's method, the `Proposed` value is discarded, and the version becomes `Current`. ## Examples - The following example checks the of a before invoking the method. + The following example checks the of a before invoking the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowVersion Example/cs/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowVersion/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRowView.xml b/xml/System.Data/DataRowView.xml index 66e92a9c753..76aa6d25045 100644 --- a/xml/System.Data/DataRowView.xml +++ b/xml/System.Data/DataRowView.xml @@ -78,12 +78,12 @@ A can have one of four different version states: `Default`, `Original`, `Current`, and `Proposed`. - After invoking on a , any edited value becomes the `Proposed` value. Until either or is invoked, the row has an `Original` and a `Proposed` version. If is invoked, the proposed version is discarded, and the value reverts to `Original`. If is invoked, the no longer has a `Proposed` version; instead, the proposed value becomes the current value. Default values are available only on rows that have columns with default values defined. + After invoking on a , any edited value becomes the `Proposed` value. Until either or is invoked, the row has an `Original` and a `Proposed` version. If is invoked, the proposed version is discarded, and the value reverts to `Original`. If is invoked, the no longer has a `Proposed` version; instead, the proposed value becomes the current value. Default values are available only on rows that have columns with default values defined. ## Examples - The following example uses the property to determine the state of a row in the . (See for another example using .) + The following example uses the property to determine the state of a row in the . (See for another example using .) :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataRowView.RowVersion1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/Overview/source.vb" id="Snippet1"::: @@ -140,14 +140,14 @@ to add a . + Use to add a . - The method is identical to the method of the . After calling , any changes made to the can be rolled back by calling . Call the method before allowing users to change row values. After values have been changed, you retrieve the new values by setting the to `DataRowVersion.Proposed`. Check the values with a business rule, and roll back the changes if needed by calling , or call to accept the changes. + The method is identical to the method of the . After calling , any changes made to the can be rolled back by calling . Call the method before allowing users to change row values. After values have been changed, you retrieve the new values by setting the to `DataRowVersion.Proposed`. Check the values with a business rule, and roll back the changes if needed by calling , or call to accept the changes. ## Examples - The following example edits a row in a . calling the before, and afterwards. + The following example edits a row in a . calling the before, and afterwards. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowView.BeginEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/BeginEdit/source.vb" id="Snippet1"::: @@ -209,12 +209,12 @@ , all changes to the row are rolled back. You can also roll back changes by calling on the parent . + After calling , all changes to the row are rolled back. You can also roll back changes by calling on the parent . ## Examples - The following example edits a row in a . The method is called to cancel the changes if the validation fails. + The following example edits a row in a . The method is called to cancel the changes if the validation fails. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowView.BeginEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/BeginEdit/source.vb" id="Snippet1"::: @@ -525,15 +525,15 @@ is invoked on the that the row belongs to. + The row is not permanently deleted until is invoked on the that the row belongs to. > [!NOTE] -> A may be invalid when a `DataRow` is deleted from the underlying table. When the becomes invalid, operations that access values associated with , such as , throw an exception. +> A may be invalid when a `DataRow` is deleted from the underlying table. When the becomes invalid, operations that access values associated with , such as , throw an exception. ## Examples - The following example uses the method on a row. + The following example uses the method on a row. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowView.Delete Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/Delete/source.vb" id="Snippet1"::: @@ -589,7 +589,7 @@ . calling the before, and afterwards. + The following example edits a row in a . calling the before, and afterwards. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/EndEdit/source.vb" id="Snippet1"::: @@ -791,7 +791,7 @@ This method checks for reference equality instead of checking whether , will be true for the returned . will be true until either is called on the , or is called again. (There is only one new row.) + After you call , will be true for the returned . will be true until either is called on the , or is called again. (There is only one new row.) ]]> diff --git a/xml/System.Data/DataSet.xml b/xml/System.Data/DataSet.xml index f7b565d3252..015506051c0 100644 --- a/xml/System.Data/DataSet.xml +++ b/xml/System.Data/DataSet.xml @@ -446,21 +446,21 @@ The following example consists of several methods that, combined, create and fil and classes have methods. Calling at the level causes the method for each to be called. Similarly, invoking on the causes to be called on each table within the . In this manner, you have multiple levels at which the method can be invoked. Calling the of the enables you to invoke the method on all subordinate objects (for example, tables and rows) with one call. + Both the and classes have methods. Calling at the level causes the method for each to be called. Similarly, invoking on the causes to be called on each table within the . In this manner, you have multiple levels at which the method can be invoked. Calling the of the enables you to invoke the method on all subordinate objects (for example, tables and rows) with one call. When you call `AcceptChanges` on the `DataSet`, any objects still in edit-mode end their edits successfully. The property of each also changes; `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. - If the `DataSet` contains objects, invoking the `AcceptChanges` method also causes the to be enforced. + If the `DataSet` contains objects, invoking the `AcceptChanges` method also causes the to be enforced. > [!NOTE] > `AcceptChanges` and `RejectChanges` only apply to `DataRow` related changes (that is, Add, Remove, Delete, and Modify). They are not applicable to schema or structural changes. > -> Calling AcceptChanges will not replicate these changes back to the data source if the DataSet was filled using a DataAdapter. In that situation, call instead. See [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters) for more information. +> Calling AcceptChanges will not replicate these changes back to the data source if the DataSet was filled using a DataAdapter. In that situation, call instead. See [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters) for more information. ## Examples - The following example adds a to a in a . The method is then called on the , which cascades to all objects that it contains. + The following example adds a to a in a . The method is then called on the , which cascades to all objects that it contains. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.AcceptChanges/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/AcceptChanges/source.vb" id="Snippet1"::: @@ -516,7 +516,7 @@ The following example consists of several methods that, combined, create and fil method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to start the initialization of a component that is used on a form or used by another component. The method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -577,7 +577,7 @@ The following example consists of several methods that, combined, create and fil property affects how sorting, searching, and filtering operations are performed on each object contained in a when using the method. + The property affects how sorting, searching, and filtering operations are performed on each object contained in a when using the method. By default, setting the property for a also sets the property of each associated to the same value. @@ -636,7 +636,7 @@ The following example consists of several methods that, combined, create and fil is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. + If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. @@ -761,7 +761,7 @@ The following example consists of several methods that, combined, create and fil If these classes have been subclassed, the copy will also be of the same subclasses. ## Examples - The following example uses the method to create a copy of the original . + The following example uses the method to create a copy of the original . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Copy Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Copy/source.vb" id="Snippet1"::: @@ -789,7 +789,7 @@ If these classes have been subclassed, the copy will also be of the same subclas ## Examples - This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. + This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. > [!NOTE] > This example shows how to use one of the overloaded versions of `CreateDataReader`. For other examples that might be available, see the individual overload topics. @@ -852,7 +852,7 @@ If these classes have been subclassed, the copy will also be of the same subclas ## Examples - The following example creates three instances, and adds each to a . The example then passes the filled `DataSet` to a procedure that calls the method, and proceeds to iterate through all the result sets contained within the . The example displays the results in the Console window. + The following example creates three instances, and adds each to a . The example then passes the filled `DataSet` to a procedure that calls the method, and proceeds to iterate through all the result sets contained within the . The example displays the results in the Console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/CreateDataReader/source1.vb" id="Snippet1"::: @@ -920,7 +920,7 @@ If these classes have been subclassed, the copy will also be of the same subclas ## Examples - This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. The example displays the results in the Console window. + This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. The example displays the results in the Console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReaderTables/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/CreateDataReader/source2.vb" id="Snippet1"::: @@ -983,7 +983,7 @@ If these classes have been subclassed, the copy will also be of the same subclas with the given . + The following example creates a new with the given . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSetName Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/DataSetName/source.vb" id="Snippet1"::: @@ -1074,7 +1074,7 @@ If these classes have been subclassed, the copy will also be of the same subclas to determine its . + This method can be called when deserializing a typed to determine its . ]]> @@ -1127,7 +1127,7 @@ If these classes have been subclassed, the copy will also be of the same subclas to determine its . + This method can be called when deserializing a typed to determine its . ]]> @@ -1182,7 +1182,7 @@ If these classes have been subclassed, the copy will also be of the same subclas to determine its . + This method can be called when deserializing a typed to determine its . ]]> @@ -1235,7 +1235,7 @@ If these classes have been subclassed, the copy will also be of the same subclas method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to end the initialization of a component that is used on a form or used by another component. The method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -1443,7 +1443,7 @@ If these classes have been subclassed, the copy will also be of the same subclas ## Examples - The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. + The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/GetChanges/source.vb" id="Snippet1"::: @@ -1502,14 +1502,14 @@ If these classes have been subclassed, the copy will also be of the same subclas method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. + The method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. - This returned copy is designed to be merged back in to this original . Relationship constraints may cause parent rows marked `Unchanged` to be included. If no rows of the desired are found, the method returns `null`. + This returned copy is designed to be merged back in to this original . Relationship constraints may cause parent rows marked `Unchanged` to be included. If no rows of the desired are found, the method returns `null`. ## Examples - The following example uses the method to create a second object, which is then used to update a data source. + The following example uses the method to create a second object, which is then used to update a data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/GetChanges/source1.vb" id="Snippet1"::: @@ -1788,9 +1788,9 @@ If these classes have been subclassed, the copy will also be of the same subclas with set to . + Calling this method is identical to calling with set to . - returns XML as a string, and therefore requires more overhead than to write XML to a file. + returns XML as a string, and therefore requires more overhead than to write XML to a file. If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. @@ -2182,9 +2182,9 @@ class Program { , except that only the primary schema is written. + Calling this method is identical to calling , except that only the primary schema is written. - returns XML as a string, and therefore requires more overhead than to write XML to a file. + returns XML as a string, and therefore requires more overhead than to write XML to a file. If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. @@ -2257,7 +2257,7 @@ class Program { method to create a second object that is then used to update a data source. + The following example uses the method to create a second object that is then used to update a data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.HasChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/HasChanges/source.vb" id="Snippet1"::: @@ -2315,12 +2315,12 @@ class Program { property of the `DataSet` before invoking the method. + Examine the property of the `DataSet` before invoking the method. ## Examples - The following example uses the method to create a second object, which is then used to update a data source. + The following example uses the method to create a second object, which is then used to update a data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/GetChanges/source1.vb" id="Snippet1"::: @@ -2384,7 +2384,7 @@ class Program { in a also has a property. Use the `HasErrors` property of the `DataSet` first, to determine if any table has errors, before checking individual objects. If a `DataTable` has errors, the method returns an array of objects containing the errors. + Each in a also has a property. Use the `HasErrors` property of the `DataSet` first, to determine if any table has errors, before checking individual objects. If a `DataTable` has errors, the method returns an array of objects containing the errors. @@ -2727,7 +2727,7 @@ class Program { . + For more information, see . ]]> @@ -2882,7 +2882,7 @@ class Program { while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. + Returns the status of the while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. ]]> @@ -2901,7 +2901,7 @@ class Program { method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. + The method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. If the `DataSet` already contains rows, the incoming data from the data source is merged with the existing rows. @@ -2994,21 +2994,21 @@ class Program { method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . + The method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . > [!NOTE] > The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. - The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. + The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. - The name resolution scheme for this method is the same as that followed by the method of the class. + The name resolution scheme for this method is the same as that followed by the method of the class. ## Examples - The following example creates a new , adds two instances to the , and then fills the using the method, retrieving data from a that contains two result sets. Finally, the example displays the contents of the tables in the console window. + The following example creates a new , adds two instances to the , and then fills the using the method, retrieving data from a that contains two result sets. Finally, the example displays the contents of the tables in the console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.LoadTables/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Load/source2.vb" id="Snippet1"::: @@ -3080,16 +3080,16 @@ class Program { method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. + The method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. > [!NOTE] > The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. The `tables` parameter allows you to specify an array of table names, indicating the order of the tables corresponding to each result set loaded from the reader. The `Load` method attempts to find a table within the `DataSet` matching the name found in the array of table names, in order. If a matching table is found, that table is loaded with the content of the current result set. If no matching table is found, a table is created using the name supplied in the array of table names, and the new table's schema is inferred from the result set. After each result set, the `Load` method moves on to the next result set within the reader, until there are no more result sets. - The default namespace associated with `DataSet`, if any, is associated with each newly created `DataTable`. The name resolution scheme for this method is the same as that followed by the method of the class. + The default namespace associated with `DataSet`, if any, is associated with each newly created `DataTable`. The name resolution scheme for this method is the same as that followed by the method of the class. @@ -3176,23 +3176,23 @@ class Program { method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . + The method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . > [!NOTE] > The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. The `errorHandler` parameter is a delegate that refers to a procedure that is called when an error occurs while loading data. The parameter passed to the procedure provides properties that allow you to retrieve information about the error that occurred, the current row of data, and the being filled. Using this delegate mechanism, rather than a simpler try/catch block, allows you to determine the error, handle the situation, and continue processing if you like. The parameter supplies a property: set this property to `true` to indicate that you have handled the error and wish to continue processing; set the property to `false` to indicate that you wish to halt processing. Be aware that setting the property to `false` causes the code that triggered the problem to throw an exception. - The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. + The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. - The name resolution scheme for this method is the same as that followed by the method of the class. + The name resolution scheme for this method is the same as that followed by the method of the class. ## Examples - The following example adds a table to a , and then attempts to use the method to load data from a that contains an incompatible schema. Rather than trapping the error, this example uses a delegate to investigate and handle the error. The output is displayed in the console window. + The following example adds a table to a , and then attempts to use the method to load data from a that contains an incompatible schema. Rather than trapping the error, this example uses a delegate to investigate and handle the error. The output is displayed in the console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.Load/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Load/source.vb" id="Snippet1"::: @@ -3253,7 +3253,7 @@ class Program { ## Remarks The property specifies the locale for which sorting applies. - By default, setting the for a also sets the for each object in that `DataSet` to the same value. + By default, setting the for a also sets the for each object in that `DataSet` to the same value. > [!NOTE] > In columns that contain expressions, the is used. The is ignored. @@ -3261,7 +3261,7 @@ class Program { ## Examples - The following example gets the for a and prints the and properties. + The following example gets the for a and prints the and properties. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Locale/source.vb" id="Snippet1"::: @@ -3327,13 +3327,13 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3392,13 +3392,13 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3409,7 +3409,7 @@ class Program { ## Examples - The following example uses the , Update, and methods on a . + The following example uses the , Update, and methods on a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Merge/source.vb" id="Snippet1"::: @@ -3470,13 +3470,13 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3547,13 +3547,13 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3564,7 +3564,7 @@ class Program { ## Examples - The following example creates a simple with one table, two columns, and ten rows. After adding ten rows, two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, the subset data is merged into the original . + The following example creates a simple with one table, two columns, and ten rows. After adding ten rows, two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, the subset data is merged into the original . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/GetChanges/source.vb" id="Snippet1"::: @@ -3627,15 +3627,15 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . + To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3699,15 +3699,15 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . + To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3718,7 +3718,7 @@ class Program { ## Examples - The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. + The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Merge/source1.vb" id="Snippet1"::: @@ -3780,13 +3780,13 @@ class Program { method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + The method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - iOn a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + iOn a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3929,14 +3929,14 @@ class Program { property is used when reading and writing an XML document into the using the , , , or methods. + The property is used when reading and writing an XML document into the using the , , , or methods. The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, if a contains a schema that was read from a document with the namespace "myCompany," and an attempt is made to read data only from a document with a different namespace, any data that does not correspond to the existing schema is ignored. ## Examples - The following example sets the before calling the method. + The following example sets the before calling the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Namespace/source.vb" id="Snippet1"::: @@ -4115,7 +4115,7 @@ class Program { ## Examples - The following example shows a class derived from the with the method overridden. + The following example shows a class derived from the with the method overridden. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.OnRemoveTable Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/OnRemoveTable/source.vb" id="Snippet1"::: @@ -4183,7 +4183,7 @@ class Program { ## Examples - The following example sets the before calling the method. + The following example sets the before calling the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Namespace/source.vb" id="Snippet1"::: @@ -4308,9 +4308,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4322,7 +4322,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema, as the following example demonstrates. + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema, as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXml/source1.vb" id="Snippet1"::: @@ -4411,9 +4411,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4425,7 +4425,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml class include the and classes. > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXml/source2.vb" id="Snippet1"::: @@ -4512,9 +4512,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4526,7 +4526,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml3 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXml/source3.vb" id="Snippet1"::: @@ -4614,9 +4614,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4628,7 +4628,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml inherits from . > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXml/source.vb" id="Snippet1"::: @@ -4718,12 +4718,12 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - The same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + The same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] -> When you use and you set to `Diffgram`, the content of the target `DataSet` and the original `DataSet` may differ because of how the diffgram is generated and processed. For more information on diffgrams, see [DiffGrams](/dotnet/framework/data/adonet/dataset-datatable-dataview/diffgrams). +> When you use and you set to `Diffgram`, the content of the target `DataSet` and the original `DataSet` may differ because of how the diffgram is generated and processed. For more information on diffgrams, see [DiffGrams](/dotnet/framework/data/adonet/dataset-datatable-dataview/diffgrams). > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4735,7 +4735,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ]]> @@ -4815,9 +4815,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4829,7 +4829,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ]]> @@ -4908,9 +4908,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4922,7 +4922,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ]]> @@ -5004,9 +5004,9 @@ class Program { method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -5018,7 +5018,7 @@ class Program { > [!NOTE] > The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. ```xml [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. ]]> @@ -5106,24 +5106,24 @@ class Program { method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method that is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . Classes that derive from the class include , , , and . > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example creates a object to read an XML schema with, and invokes the method with the object. + The following example creates a object to read an XML schema with, and invokes the method with the object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXmlSchema/source1.vb" id="Snippet1"::: @@ -5190,24 +5190,24 @@ class Program { method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method that is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . Classes that inherit from the class include the and classes. > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example creates a object to read a schema with, and invokes the method with the object. + The following example creates a object to read a schema with, and invokes the method with the object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXmlSchema/source2.vb" id="Snippet1"::: @@ -5273,17 +5273,17 @@ class Program { method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method that is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. @@ -5355,24 +5355,24 @@ class Program { method to create the schema for a . The schema includes table, relation, and constraint definitions. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method that is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . The class is abstract. A class that inherits from the `XmlReader` is the class. > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. ## Examples - The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. + The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXmlSchema/source.vb" id="Snippet1"::: @@ -5480,18 +5480,18 @@ class Program { to call the method on all objects contained by the . + Invoke the to call the method on all objects contained by the . - objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. + objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. - When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). + When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). AcceptChanges and RejectChanges only apply to related changes (that is, `Add`, `Remove`, `Delete`, and `Modify`). They are not applicable to schema or structural changes. ## Examples - The following example shows a class derived from the class. The event is invoked from within a function. + The following example shows a class derived from the class. The event is invoked from within a function. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.RejectChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/RejectChanges/source.vb" id="Snippet1"::: @@ -5715,7 +5715,7 @@ class Program { is supported in version 2.0 of the .NET Framework or later. - When is set, only the top level runtime properties present on the are serialized. In addition, they are serialized only if they happen to be different from the default values. None of the `Tables`, `Relations` or `Constraints` are serialized. The serialized runtime properties include , , , , , and . These properties are serialized to make sure that overall runtime data integrity is preserved. + When is set, only the top level runtime properties present on the are serialized. In addition, they are serialized only if they happen to be different from the default values. None of the `Tables`, `Relations` or `Constraints` are serialized. The serialized runtime properties include , , , , , and . These properties are serialized to make sure that overall runtime data integrity is preserved. ]]> @@ -5772,7 +5772,7 @@ class Program { ## Examples - The following examples show a class derived from the class. The and methods are invoked from within functions in the derived class. + The following examples show a class derived from the class. The and methods are invoked from within functions in the derived class. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeRelations Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ShouldSerializeRelations/source.vb" id="Snippet1"::: @@ -5832,7 +5832,7 @@ class Program { ## Examples - The following example shows a class derived from the class. The method is called from within functions in the derived class. + The following example shows a class derived from the class. The method is called from within functions in the derived class. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeTables Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ShouldSerializeTables/source.vb" id="Snippet1"::: @@ -6262,7 +6262,7 @@ class Program { method of the . To remove tables, use the method. + To add tables to the collection, use method of the . To remove tables, use the method. @@ -6345,9 +6345,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6355,7 +6355,7 @@ class Program { ## Examples - The following example creates a object. The object is then used with the method to write an XML document. + The following example creates a object. The object is then used with the method to write an XML document. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXml/source.vb" id="Snippet1"::: @@ -6422,9 +6422,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6490,9 +6490,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6561,9 +6561,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6632,9 +6632,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6703,9 +6703,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6713,7 +6713,7 @@ class Program { ## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/ReadXml/source2.vb" id="Snippet1"::: @@ -6781,9 +6781,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6791,7 +6791,7 @@ class Program { ## Examples - The following example uses the method to write an XML document. + The following example uses the method to write an XML document. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml7 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXml/source2.vb" id="Snippet1"::: @@ -6862,9 +6862,9 @@ class Program { into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + The `WriteXml` method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -6872,7 +6872,7 @@ class Program { ## Examples - The following example creates a object that is used to create a new . The object is used with the method to write an XML document. + The following example creates a object that is used to create a new . The object is used with the method to write an XML document. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXml/source1.vb" id="Snippet1"::: @@ -6950,18 +6950,18 @@ class Program { method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Classes that derive from the class include , , , and . ## Examples - The following example creates a new object that is passed to the method to write the schema to disk. + The following example creates a new object that is passed to the method to write the schema to disk. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXmlSchema/source.vb" id="Snippet1"::: @@ -7028,18 +7028,18 @@ class Program { method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Classes the derive from the class include the , , , , and . ## Examples - The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. + The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXmlSchema/source1.vb" id="Snippet1"::: @@ -7105,11 +7105,11 @@ class Program { method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. @@ -7181,18 +7181,18 @@ class Program { method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. One class that inherits from the class is the class. ## Examples - The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. + The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/WriteXmlSchema/source2.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataSetDateTime.xml b/xml/System.Data/DataSetDateTime.xml index 5b9918af127..c998099272e 100644 --- a/xml/System.Data/DataSetDateTime.xml +++ b/xml/System.Data/DataSetDateTime.xml @@ -47,9 +47,9 @@ cannot be set on non- columns. Setting the property with the default value UnspecifiedLocal on non- columns is permitted. Modifying the column data type from to any other type resets the to the default value UnspecifiedLocal. + cannot be set on non- columns. Setting the property with the default value UnspecifiedLocal on non- columns is permitted. Modifying the column data type from to any other type resets the to the default value UnspecifiedLocal. - Checking schema for merging, Relations, and ForeignKeyConstraints can be performed between columns with matching properties. Otherwise the columns should be considered as non-matching on schema. The only exception is between Unspecified and UnspecifiedLocal. It is permitted to have a relation or a `ForeignKeyConstraint` between two `DateTime` columns with one in `Unspecified` and other in `UnspecifiedLocal` . + Checking schema for merging, Relations, and ForeignKeyConstraints can be performed between columns with matching properties. Otherwise the columns should be considered as non-matching on schema. The only exception is between Unspecified and UnspecifiedLocal. It is permitted to have a relation or a `ForeignKeyConstraint` between two `DateTime` columns with one in `Unspecified` and other in `UnspecifiedLocal` . ]]> diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index 4b89630a607..e843910ef65 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -424,14 +424,14 @@ The following example creates two objects and one < is called, any object still in edit mode successfully ends its edits. The also changes: all `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. + When is called, any object still in edit mode successfully ends its edits. The also changes: all `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. - The method is generally called on a after you attempt to update the using the method. + The method is generally called on a after you attempt to update the using the method. ## Examples - The following example tests each table for errors. If the table's errors can be reconciled (by passing it to an undefined function), is called; otherwise, is called. + The following example tests each table for errors. If the table's errors can be reconciled (by passing it to an undefined function), is called; otherwise, is called. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.AcceptChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/AcceptChanges/source.vb" id="Snippet1"::: @@ -489,7 +489,7 @@ The following example creates two objects and one < method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to start the initialization of a component that is used on a form or used by another component. The method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -539,7 +539,7 @@ The following example creates two objects and one < in conjunction with and . + Use in conjunction with and . ]]> @@ -601,7 +601,7 @@ The following example creates two objects and one < ## Examples - The following example calls the method twice on a . The first time, the property is set to `false`, the second, to `true`. + The following example calls the method twice on a . The first time, the property is set to `false`, the second, to `true`. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.CaseSensitive Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/CaseSensitive/source.vb" id="Snippet1"::: @@ -672,7 +672,7 @@ The following example creates two objects and one < A defines the relationship between two tables. Typically, two tables are linked through a single field that contains the same data. For example, a table that contains address data may have a single field containing codes that represent countries/regions. A second table that contains country/region data will have a single field that contains the code that identifies the country/region, and it is this code that is inserted into the corresponding field in the first table. A , then, contains at least four pieces of information: (1) the name of the first table, (2) the column name in the first table, (3) the name of the second table, and (4) the column name in the second table. ## Examples - The following example uses the property to return each child in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. + The following example uses the property to return each child in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ChildRelations Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ChildRelations/source.vb" id="Snippet1"::: @@ -730,7 +730,7 @@ The following example creates two objects and one < ## Remarks All rows in all tables are removed. An exception is generated if the table has any enforced child relations that would cause child rows to be orphaned. - If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. When you use to create new rows, the rows must be processed before you call . + If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. When you use to create new rows, the rows must be processed before you call . @@ -792,7 +792,7 @@ The following example creates two objects and one < ## Remarks If these classes have been derived, the clone will also be of the same derived classes. - Clone creates a new with the same structure as the original , but does not copy any data (the new will not contain any `DataRows`). To copy both the structure and data into a new , use . + Clone creates a new with the same structure as the original , but does not copy any data (the new will not contain any `DataRows`). To copy both the structure and data into a new , use . ## Examples The following sample demonstrates how to update the structure and constraints of the destination table after you execute DataTable.Clone. The ClonedDataTable class will return a destination table and includes all the updating events. After the clone, structure changes in the source table won't be reflected in the destination table. Specifically, this sample will: @@ -1584,7 +1584,7 @@ class Program { `"Quantity * UnitPrice"` - The expression argument for the method would then be this: + The expression argument for the method would then be this: `Sum(total)` @@ -1733,7 +1733,7 @@ class Program { method to create a copy of the original . The namespace name is not retained if it is inherited from a parent or . + The following example uses the method to create a copy of the original . The namespace name is not retained if it is inherited from a parent or . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Copy Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Copy/source.vb" id="Snippet1"::: @@ -1788,7 +1788,7 @@ class Program { instance. The example then passes the filled to a procedure that calls the method, which iterates through the results contained within the . + The following console application creates a instance. The example then passes the filled to a procedure that calls the method, which iterates through the results contained within the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.CreateDataReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/CreateDataReader/source.vb" id="Snippet1"::: @@ -2103,7 +2103,7 @@ class Program { method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to end the initialization of a component that is used on a form or used by another component. The method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -2153,7 +2153,7 @@ class Program { in conjunction with and . + Use in conjunction with and . ]]> @@ -2213,7 +2213,7 @@ class Program { to add custom information to a . Add information with the `Add` method. Retrieve information with the `Item` method. + Use the to add custom information to a . Add information with the `Add` method. Retrieve information with the `Item` method. Extended properties must be of type . Properties that are not of type String are not persisted when the is written as XML. @@ -2390,7 +2390,7 @@ class Program { method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. + The method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. Relationship constraints may cause unchanged parent rows to be included. @@ -2504,12 +2504,12 @@ class Program { objects that have set. For example, errors can occur when calling with set to `true`. Do not invoke on the until you resolve all errors and resubmit the for updating. + Returns the list of objects that have set. For example, errors can occur when calling with set to `true`. Do not invoke on the until you resolve all errors and resubmit the for updating. ## Examples - The following example uses the method to return an array of objects that have errors. + The following example uses the method to return an array of objects that have errors. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.GetErrors Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/GetErrors/source.vb" id="Snippet1"::: @@ -2733,11 +2733,11 @@ class Program { , you can mark each change with an error if the change causes some validation failure. You can mark an entire with an error message using the property. You can also set errors on each column of the row with the method. + As users work on a set of data contained in a , you can mark each change with an error if the change causes some validation failure. You can mark an entire with an error message using the property. You can also set errors on each column of the row with the method. - Before updating a data source with a , it's recommended that you first invoke the method on the target . The method results in a that contains only the changes made to the original. Before sending the to the data source for updating, check the property of each table to see if any errors have been attached to the rows or columns in the rows. + Before updating a data source with a , it's recommended that you first invoke the method on the target . The method results in a that contains only the changes made to the original. Before sending the to the data source for updating, check the property of each table to see if any errors have been attached to the rows or columns in the rows. - After reconciling each error, clear the errors with the method of the `DataRow`. + After reconciling each error, clear the errors with the method of the `DataRow`. @@ -2800,13 +2800,13 @@ class Program { adds a row to the table using the existing table schema, but with default values for the row, and sets the to `Detached`. Calling preserves the existing along with other values in the row. If the `DataRow` that is passed as a parameter is in a detached state, it is ignored, and no exception is thrown. + Calling adds a row to the table using the existing table schema, but with default values for the row, and sets the to `Detached`. Calling preserves the existing along with other values in the row. If the `DataRow` that is passed as a parameter is in a detached state, it is ignored, and no exception is thrown. The new row will be added to the end of the data table. If the new row violates a Constraint it won't be added to the data table. - You can get the index of the new row with as DataTable.Rows.Find and DataTable.Rows.IndexOf. See and for more information. + You can get the index of the new row with as DataTable.Rows.Find and DataTable.Rows.IndexOf. See and for more information. ]]> @@ -2865,7 +2865,7 @@ class Program { . + For more information, see . ]]> @@ -2925,7 +2925,7 @@ class Program { while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. + Returns the status of the while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. ]]> @@ -2970,7 +2970,7 @@ class Program { ## Examples - The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then focuses on data issues, including handling the various loading options. + The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then focuses on data issues, including handling the various loading options. > [!NOTE] > This example shows how to use one of the overloaded versions of `Load`. For other examples that might be available, see the individual overload topics. @@ -3035,20 +3035,20 @@ class Program { method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. + The method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. - The method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. + The method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. |Condition|Behavior| |---------------|--------------| -|The has no schema.|The method infers the schema based on the result set from the imported .| -|The has a schema, but it is incompatible with the loaded schema.|The method throws an exception corresponding to the particular error that occurs when attempting to load data into the incompatible schema.| -|The schemas are compatible, but the loaded result set schema contains columns that do not exist in the .|The method adds the extra columns to `DataTable`'s schema. The method throws an exception if corresponding columns in the and the loaded result set are not value compatible. The method also retrieves constraint information from the result set for all added columns. Except for the case of Primary Key constraint, this constraint information is used only if the current does not contain any columns at the start of the load operation.| -|The schemas are compatible, but the loaded result set schema contains fewer columns than does the `DataTable`.|If a missing column has a default value defined or the column's data type is nullable, the method allows the rows to be added, substituting the default or `null` value for the missing column. If no default value or `null` can be used, then the `Load` method throws an exception. If no specific default value has been supplied, the `Load` method uses the `null` value as the implied default value.| +|The has no schema.|The method infers the schema based on the result set from the imported .| +|The has a schema, but it is incompatible with the loaded schema.|The method throws an exception corresponding to the particular error that occurs when attempting to load data into the incompatible schema.| +|The schemas are compatible, but the loaded result set schema contains columns that do not exist in the .|The method adds the extra columns to `DataTable`'s schema. The method throws an exception if corresponding columns in the and the loaded result set are not value compatible. The method also retrieves constraint information from the result set for all added columns. Except for the case of Primary Key constraint, this constraint information is used only if the current does not contain any columns at the start of the load operation.| +|The schemas are compatible, but the loaded result set schema contains fewer columns than does the `DataTable`.|If a missing column has a default value defined or the column's data type is nullable, the method allows the rows to be added, substituting the default or `null` value for the missing column. If no default value or `null` can be used, then the `Load` method throws an exception. If no specific default value has been supplied, the `Load` method uses the `null` value as the implied default value.| Before considering the behavior of the `Load` method in terms of data operations, consider that each row within a maintains both the current value and the original value for each column. These values may be equivalent, or may be different if the data in the row has been changed since filling the `DataTable`. For more information, see [Row States and Row Versions](/dotnet/framework/data/adonet/dataset-datatable-dataview/row-states-and-row-versions). - This version of the `Load` method attempts to preserve the current values in each row, leaving the original value intact. (If you want finer control over the behavior of incoming data, see .) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. + This version of the `Load` method attempts to preserve the current values in each row, leaving the original value intact. (If you want finer control over the behavior of incoming data, see .) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value depends on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. @@ -3062,14 +3062,14 @@ class Program { |Unchanged|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| |(Not present)|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| - Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. + Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. To determine which version of the primary key field to use for comparing the current row with an incoming row, the `Load` method uses the original version of the primary key value within a row, if it exists. Otherwise, the `Load` method uses the current version of the primary key field. ## Examples - The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then calls the `Load` method, displaying the data both before and after the load operation. + The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then calls the `Load` method, displaying the data both before and after the load operation. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableLoad.IDataReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Load/source2.vb" id="Snippet1"::: @@ -3133,7 +3133,7 @@ class Program { , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. + The `Load` method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. The `Load` method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the `Load` method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. @@ -3162,7 +3162,7 @@ class Program { |Unchanged|Current = \

Original = \

If new value is the same as the existing value then

State = \

RowAction = Nothing

Else

State = \

RowAction = Change|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| Not present)|Current = \

Original = \

State = \

RowAction = Add|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| - Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. + Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. If you specify the OverwriteChanges or PreserveChanges options when calling the `Load` method, then the assumption is made that the incoming data is coming from the `DataTable`'s primary data source, and the DataTable tracks changes and can propagate the changes back to the data source. If you select the Upsert option, it is assumed that the data is coming from one of a secondary data source, such as data provided by a middle-tier component, perhaps altered by a user. In this case, the assumption is that the intent is to aggregate data from one or more data sources in the `DataTable`, and then perhaps propagate the data back to the primary data source. The parameter is used for determining the specific version of the row that is to be used for primary key comparison. The table below provides the details. @@ -3175,7 +3175,7 @@ Not present)|Current = \

Original = \
## Examples - The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then focuses on data issues, including handling the various loading options. + The following example demonstrates several of the issues involved with calling the method. First, the example focuses on schema issues, including inferring a schema from the loaded , and then handling incompatible schemas, and schemas with missing or additional columns. The example then focuses on data issues, including handling the various loading options. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableLoad.LoadOption/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Load/source3.vb" id="Snippet1"::: @@ -3249,7 +3249,7 @@ Not present)|Current = \

Original = \
, and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. + The `Load` method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. The `Load` method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the `Load` method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. @@ -3278,7 +3278,7 @@ eleted|(Load does not affect deleted rows)

Current = ---

|Unchanged|Current = \

Original = \

If new value is the same as the existing value then

State = \

RowAction = Nothing

Else

State = \

RowAction = Change|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| Not present)|Current = \

Original = \

State = \

RowAction = Add|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal|Current = \

Original = \

State = \

RowAction = ChangeCurrentAndOriginal| - Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. + Values in a can be constrained through use of properties such as and . The `Load` method handles such columns in a manner that is consistent with the behavior defined by the column's properties. The read only constraint on a is applicable only for changes that occur in memory. The `Load` method's overwrites the read-only column values, if needed. If you specify the OverwriteChanges or PreserveChanges options when calling the `Load` method, then the assumption is made that the incoming data is coming from the `DataTable`'s primary data source, and the DataTable tracks changes and can propagate the changes back to the data source. If you select the Upsert option, it is assumed that the data is coming from one of a secondary data source, such as data provided by a middle-tier component, perhaps altered by a user. In this case, the assumption is that the intent is to aggregate data from one or more data sources in the `DataTable`, and then perhaps propagate the data back to the primary data source. The parameter is used for determining the specific version of the row that is to be used for primary key comparison. The table below provides the details. @@ -3371,20 +3371,20 @@ Not present)|Current = \

Original = \
method takes an array of values and finds the matching value(s) in the primary key column(s). + The method takes an array of values and finds the matching value(s) in the primary key column(s). If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. - If the `fAcceptChanges` parameter is `true` or not specified, the new data is added and then is called to accept all changes in the ; if the argument is `false`, newly added rows are marked as insertions, and changes to existing rows are marked as modifications. + If the `fAcceptChanges` parameter is `true` or not specified, the new data is added and then is called to accept all changes in the ; if the argument is `false`, newly added rows are marked as insertions, and changes to existing rows are marked as modifications. Exceptions can also occur during either a or event. If an exception occurs, the row is not added to the table. - Use in conjunction with and . + Use in conjunction with and . ## Examples - The following example uses the method to attempt to find a row. If no such row is found, the values are used to create a new row. + The following example uses the method to attempt to find a row. If no such row is found, the values are used to create a new row. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.LoadDataRow Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/LoadDataRow/source.vb" id="Snippet1"::: @@ -3455,7 +3455,7 @@ Not present)|Current = \

Original = \
method takes an array of values and finds the matching value(s) in the primary key column(s). + The method takes an array of values and finds the matching value(s) in the primary key column(s). If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. @@ -3463,7 +3463,7 @@ Not present)|Current = \

Original = \
Exceptions can also occur during either a or event. If an exception occurs, the row is not added to the table. - Use in conjunction with and . + Use in conjunction with and . ]]> @@ -3529,7 +3529,7 @@ Not present)|Current = \

Original = \
## Examples - The following example sets the through the and prints the ISO language name. + The following example sets the through the and prints the ISO language name. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Locale Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Locale/source.vb" id="Snippet1"::: @@ -3559,7 +3559,7 @@ Not present)|Current = \

Original = \
## Examples - The following console application demonstrates the behavior of the `missingSchemaAction` parameter of the method. This example creates two versions of the same table, modifying the schema for the second version. The code then attempts to merge the second table into the first. + The following console application demonstrates the behavior of the `missingSchemaAction` parameter of the method. This example creates two versions of the same table, modifying the schema for the second version. The code then attempts to merge the second table into the first. > [!NOTE] > This example shows how to use one of the overloaded versions of Merge. For other examples that might be available, see the individual overload topics. @@ -3625,14 +3625,14 @@ Not present)|Current = \

Original = \
When performing a merge, changes made to the existing data before the merge are preserved by default during the merge operation. Developers can modify this behavior by calling one of the other two overloads for this method, and specifying a false value for the `preserveChanges` parameter. - In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted`, is matched to target rows with the same primary key values. Source rows with a value of `Added` are matched to new target rows with the same primary key values as the new source rows. ## Examples - The following console application creates a simple and adds data to the table. The example then creates a copy of the table, adding rows to the copy. Finally, the example calls the method to merge the data in the second table with the data in the first table. + The following console application creates a simple and adds data to the table. The example then creates a copy of the table, adding rows to the copy. Finally, the example calls the method to merge the data in the second table with the data in the first table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.Merge/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Merge/source.vb" id="Snippet1"::: @@ -3699,7 +3699,7 @@ Not present)|Current = \

Original = \
When performing a merge, changes made to the existing data before the merge are preserved during the merge operation unless the developer specifies false for the `preserveChanges` parameter. If the `preserveChanges` parameter is set to `true`, incoming values do not overwrite existing values in the Current row version of the existing row. If the `preserveChanges` parameter is set to `false`, incoming values do overwrite the existing values in the Current row version of the existing row. For more information about row versions, see [Row States and Row Versions](/dotnet/framework/data/adonet/dataset-datatable-dataview/row-states-and-row-versions). - In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus this subset is more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus this subset is more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a value of `Added` are matched to new target rows with the same primary key values as the new source rows. @@ -3775,9 +3775,9 @@ Not present)|Current = \

Original = \
When performing a merge, changes made to the existing data before the merge are preserved during the merge operation unless the developer specifies false for the `preserveChanges` parameter. If the `preserveChanges` parameter is set to `true`, incoming values do not overwrite existing values in the Current row version of the existing row. If the `preserveChanges` parameter is set to `false`, incoming values do overwrite the existing values in the Current row version of the existing row. For more information about row versions, see [Row States and Row Versions](/dotnet/framework/data/adonet/dataset-datatable-dataview/row-states-and-row-versions). - In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus this subset is more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + In a client application, it is usual to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus this subset is more efficiently passed back to a middle tier component. The middle tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - When the method is called, the schemas of the two objects are compared, because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + When the method is called, the schemas of the two objects are compared, because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. After merging schemas, the data is merged. @@ -3786,7 +3786,7 @@ Not present)|Current = \

Original = \
## Examples - The following console application demonstrates the behavior of the `missingSchemaAction` parameter of the method. This example creates two versions of the same table, modifying the schema for the second version. The code then attempts to merge the second table into the first. + The following console application demonstrates the behavior of the `missingSchemaAction` parameter of the method. This example creates two versions of the same table, modifying the schema for the second version. The code then attempts to merge the second table into the first. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.MergeMissingSchemaAction/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Merge/source1.vb" id="Snippet1"::: @@ -3850,12 +3850,12 @@ Not present)|Current = \

Original = \
allows the system to create an appropriate set of resources before fetching data. In a situation when performance is critical, setting this property can optimize performance. + The allows the system to create an appropriate set of resources before fetching data. In a situation when performance is critical, setting this property can optimize performance. ## Examples - The following example sets the of a . + The following example sets the of a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.MinimumCapacity Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/MinimumCapacity/source.vb" id="Snippet1"::: @@ -3958,12 +3958,12 @@ Not present)|Current = \

Original = \
method to create new objects with the same schema as the . After creating a , you can add it to the , through the object's property. When you use to create new rows, the rows must be added to or deleted from the data table before you call . + You must use the method to create new objects with the same schema as the . After creating a , you can add it to the , through the object's property. When you use to create new rows, the rows must be added to or deleted from the data table before you call . ## Examples - The following example creates a , adds two objects that determine the table's schema, and creates several new objects using the method. Those objects are then added to the using the method. + The following example creates a , adds two objects that determine the table's schema, and creates several new objects using the method. Those objects are then added to the using the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.NewRow Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/NewRow/source.vb" id="Snippet1"::: @@ -4584,7 +4584,7 @@ Not present)|Current = \

Original = \
event, which is fired immediately after all rows have been successfully cleared but before the method returns control back to the caller. + Raises the event, which is fired immediately after all rows have been successfully cleared but before the method returns control back to the caller. Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). @@ -4639,7 +4639,7 @@ Not present)|Current = \

Original = \
event, which is fired before processing of the operation begins. + Raises the event, which is fired before processing of the operation begins. Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). @@ -4694,7 +4694,7 @@ Not present)|Current = \

Original = \
event, which fires after a new has been created using . + Raises the event, which fires after a new has been created using . Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). @@ -4761,7 +4761,7 @@ Not present)|Current = \

Original = \
property to return each parent in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. + The following example uses the property to return each parent in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ParentRelations Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ParentRelations/source.vb" id="Snippet1"::: @@ -4922,9 +4922,9 @@ Not present)|Current = \

Original = \
method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that include the `XmlReadMode` parameter, and set its value to `ReadSchema`. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that include the `XmlReadMode` parameter, and set its value to `ReadSchema`. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -4992,11 +4992,11 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. - The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -5011,7 +5011,7 @@ Not present)|Current = \

Original = \
## Examples - The following example creates a containing two columns and ten rows. The example writes the schema and data to a memory stream, by invoking the method. The example creates a second and calls the method to fill it with schema and data. + The following example creates a containing two columns and ten rows. The example writes the schema and data to a memory stream, by invoking the method. The example creates a second and calls the method to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.ReadXml/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ReadXml/source.vb" id="Snippet1"::: @@ -5078,11 +5078,11 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. - The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -5097,7 +5097,7 @@ Not present)|Current = \

Original = \
## Examples - The following example creates a containing two columns and ten rows. The example writes the schema and data to a memory stream, by invoking the method. The example creates a second and calls the method to fill it with schema and data. + The following example creates a containing two columns and ten rows. The example writes the schema and data to a memory stream, by invoking the method. The example creates a second and calls the method to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.ReadXmlText/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ReadXml/source2.vb" id="Snippet1"::: @@ -5163,11 +5163,11 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. - The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -5200,7 +5200,7 @@ public class A { ## Examples - The following example creates a containing two columns and ten rows. The example writes the schema and data to disk. The example creates a second and calls the method to fill it with schema and data. + The following example creates a containing two columns and ten rows. The example writes the schema and data to disk. The example creates a second and calls the method to fill it with schema and data. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.ReadXmlString/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ReadXml/source1.vb" id="Snippet1"::: @@ -5267,11 +5267,11 @@ public class A { and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. - The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. + The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataTable`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -5286,7 +5286,7 @@ public class A { ## Examples - The following example creates a containing two columns and ten rows. The example writes the schema and data to an . The example creates a second and calls the method to fill it with schema and data from the instance. + The following example creates a containing two columns and ten rows. The example writes the schema and data to an . The example creates a second and calls the method to fill it with schema and data from the instance. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.ReadXmlXmlReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ReadXml/source3.vb" id="Snippet1"::: @@ -5310,11 +5310,11 @@ public class A { ## Remarks Use the `ReadXmlSchema` method to create the schema for a . The schema includes table, relation, and constraint definitions. - To write a schema to an XML document, use the method. + To write a schema to an XML document, use the method. The XML schema is interpreted according to the XSD standard. - The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . ]]> @@ -5378,15 +5378,15 @@ public class A { method to create the schema for a . The schema includes table, relation, and constraint definitions. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. - To write a schema to an XML document, use the method. + To write a schema to an XML document, use the method. The XML schema is interpreted according to the XSD standard. Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . To create a nested relation using XML schema, use implicit nested elements. You can also configure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5460,15 +5460,15 @@ public class A { method to create the schema for a . The schema includes table, relation, and constraint definitions. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. - To write a schema to an XML document, use the method. + To write a schema to an XML document, use the method. The XML schema is interpreted according to the XSD standard. Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . To create a nested relation using XML schema, use implicit nested elements. You can also reconfigure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5541,15 +5541,15 @@ public class A { method to create the schema for a . The schema includes table, relation, and constraint definitions. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. - To write a schema to an XML document, use the method. + To write a schema to an XML document, use the method. The XML schema is interpreted according to the XSD standard. Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the `DataTable`. + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the `DataTable`. To create a nested relation using XML schema, use implicit nested elements. You can also reconfigure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5623,15 +5623,15 @@ public class A { method to create the schema for a . The schema includes table, relation, and constraint definitions. + Use the method to create the schema for a . The schema includes table, relation, and constraint definitions. - To write a schema to an XML document, use the method. + To write a schema to an XML document, use the method. The XML schema is interpreted according to the XSD standard. Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . > [!NOTE] > The way to create a nested relation using XML schema is to have implicit nested elements. Additionally, the nested relation could be re-wired, to use explicit column names. It is mandatory for elements to be implicitly nested for the corresponding DataTables to participate in a nested relation. @@ -5748,12 +5748,12 @@ public class A { is called, any objects that are still in edit-mode cancel their edits. New rows are removed. Rows with the set to `Modified` or `Deleted` return back to their original state. + When is called, any objects that are still in edit-mode cancel their edits. New rows are removed. Rows with the set to `Modified` or `Deleted` return back to their original state. ## Examples - The following example makes several changes to a , but rejects the changes by invoking the method. + The following example makes several changes to a , but rejects the changes by invoking the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.RejectChanges Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/RejectChanges/source.vb" id="Snippet1"::: @@ -6174,14 +6174,14 @@ public class A { , you must use the method to return a new object. Such an object is automatically configured according to the schema defined for the through its collection of objects. After creating a new row and setting the values for each column in the row, add the row to the using the `Add` method. + To create a new , you must use the method to return a new object. Such an object is automatically configured according to the schema defined for the through its collection of objects. After creating a new row and setting the values for each column in the row, add the row to the using the `Add` method. - Each in the collection represents a row of data in the table. To commit a change to the value of a column in the row, you must invoke the method. + Each in the collection represents a row of data in the table. To commit a change to the value of a column in the row, you must invoke the method. ## Examples - The following shows two examples of returning and setting rows. The first example uses the property and prints the value of each column for every row. The second example uses the object's method to create a new object with the schema of the . After setting the row values, the row is added to the through the `Add` method. + The following shows two examples of returning and setting rows. The first example uses the property and prints the value of each column for every row. The second example uses the object's method to create a new object with the schema of the . After setting the row values, the row is added to the through the `Add` method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Rows Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Rows/source.vb" id="Snippet1"::: @@ -6255,7 +6255,7 @@ public class A { ## Examples - The following example returns an array of objects through the method. + The following example returns an array of objects through the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Select Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Select/source.vb" id="Snippet1"::: @@ -6409,7 +6409,7 @@ To ensure the proper sort order, specify sort criteria with class's property value. The `Sort` argument also uses the same rules for creating class's strings. + To form the `filterExpression` argument, use the same rules for creating the class's property value. The `Sort` argument also uses the same rules for creating class's strings. If the column on the filter contains a null value, it will not be part of the result. @@ -6490,7 +6490,7 @@ To ensure the proper sort order, specify sort criteria with class's property value. The `Sort` argument also uses the same rules for creating class's strings. + To form the `filterExpression` argument, use the same rules for creating the class's property value. The `Sort` argument also uses the same rules for creating class's strings. If the column on the filter contains a null value, it will not be part of the result. @@ -6919,7 +6919,7 @@ To ensure the proper sort order, specify sort criteria with event is fired immediately after all rows have been successfully cleared but before the method returns control back to the caller. The event is not fired if there are any exceptions during the clear operation. + The event is fired immediately after all rows have been successfully cleared but before the method returns control back to the caller. The event is not fired if there are any exceptions during the clear operation. ]]> @@ -6975,7 +6975,7 @@ To ensure the proper sort order, specify sort criteria with event is fired before processing of the operation begins. This event is always fired when the method is invoked, even if the table contains zero rows. + The event is fired before processing of the operation begins. This event is always fired when the method is invoked, even if the table contains zero rows. ]]> @@ -7040,12 +7040,12 @@ To ensure the proper sort order, specify sort criteria with is used to return this table from the parent object's (returned by the property). + The is used to return this table from the parent object's (returned by the property). ## Examples - The following example prints the for each table in a collection of objects. + The following example prints the for each table in a collection of objects. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.TableName Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/TableName/source.vb" id="Snippet1"::: @@ -7108,7 +7108,7 @@ To ensure the proper sort order, specify sort criteria with has been created using . This event is fired before the invoked `NewRow` method returns. The new instance is detached; it has not been added to the collection. + Fires after a new has been created using . This event is fired before the invoked `NewRow` method returns. The new instance is detached; it has not been added to the collection. ]]> @@ -7160,12 +7160,12 @@ To ensure the proper sort order, specify sort criteria with and for the . + Gets the and for the . ## Examples - The following example returns the and using the method. + The following example returns the and using the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ToString Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ToString/source.vb" id="Snippet1"::: @@ -7187,9 +7187,9 @@ To ensure the proper sort order, specify sort criteria with method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7197,7 +7197,7 @@ To ensure the proper sort order, specify sort criteria with instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. + The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. > [!NOTE] > This example shows how to use one of the overloaded versions of WriteXml. For other examples that might be available, see the individual overload topics. @@ -7404,9 +7404,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7472,9 +7472,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7539,9 +7539,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7607,9 +7607,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7677,11 +7677,11 @@ sdata:PrimaryKey="true"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all of its descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -7751,9 +7751,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7821,7 +7821,7 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all its descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -7831,7 +7831,7 @@ sdata:PrimaryKey="true"> ## Examples - The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to `true`. + The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to `true`. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.WriteXml/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/WriteXml/source.vb" id="Snippet1"::: @@ -7899,9 +7899,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -7968,9 +7968,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all of its descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8039,9 +8039,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -8109,9 +8109,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8181,9 +8181,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. > [!NOTE] > An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . @@ -8253,13 +8253,13 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a `DataTable` into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `XmlWriteMode` parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a `DataTable` into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `XmlWriteMode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally, the `WriteXml` method saves data only for the current table. The `WriteXml` method provides a way to write either data only, or both data and schema from a `DataTable` into an XML document, whereas the `WriteXmlSchema` method writes only the schema. To write both data and schema, use one of the overloads that includes the `XmlWriteMode` parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all of its descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8331,13 +8331,13 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - Normally, the `WriteXml` method saves data only for the current table. The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. + Normally, the `WriteXml` method saves data only for the current table. The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all of its descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8347,7 +8347,7 @@ sdata:PrimaryKey="true"> ## Examples - The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. + The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.WriteXmlIO/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/WriteXml/source1.vb" id="Snippet1"::: @@ -8554,13 +8554,13 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - Normally, the `WriteXml` method saves data only for the current table. If you want to save the data for the current table and all of schema, the method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + Normally, the `WriteXml` method saves data only for the current table. If you want to save the data for the current table and all of schema, the method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and all descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8632,9 +8632,9 @@ sdata:PrimaryKey="true"> method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. + The method provides a way to write either data only, or both data and schema from a into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that include the parameter, and set its value to `WriteSchema`. - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataTable`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. Normally the `WriteXml` method writes the data only for the current table. To write the data for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -8658,16 +8658,16 @@ sdata:PrimaryKey="true"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. ## Examples - The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. + The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. > [!NOTE] > This example shows how to use one of the overloaded versions of `WriteXmlSchema` For other examples that might be available, see the individual overload topics. @@ -8809,11 +8809,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. ]]> @@ -8876,11 +8876,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. ]]> @@ -8942,11 +8942,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. ]]> @@ -9009,11 +9009,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. ]]> @@ -9078,11 +9078,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Normally the `WriteXmlSchema` method writes the schema only for the current table. To write the schema for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -9149,18 +9149,18 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Normally the `WriteXmlSchema` method writes the schema only for the current table. To write the schema for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. ## Examples - The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. + The following console application creates two instances, adds each to a , creates a relating the two tables, and then uses the method to write the data contained within the parent table to a . The example demonstrates the behavior when setting the `writeHierarchy` parameter to each of its values. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTable.WriteXmlSchema/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/WriteXmlSchema/source.vb" id="Snippet1"::: @@ -9300,11 +9300,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Normally the `WriteXmlSchema` method writes the schema only for the current table. To write the schema for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. @@ -9371,11 +9371,11 @@ xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. + Use the method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. The XML schema is written using the XSD standard. - To write the data to an XML document, use the method. + To write the data to an XML document, use the method. Normally the `WriteXmlSchema` method writes the schema only for the current table. To write the schema for the current table and its entire descendant, related tables, call the method with the `writeHierarchy` parameter set to `true`. diff --git a/xml/System.Data/DataTableCollection.xml b/xml/System.Data/DataTableCollection.xml index dc8a39461b3..74d1ba0f14e 100644 --- a/xml/System.Data/DataTableCollection.xml +++ b/xml/System.Data/DataTableCollection.xml @@ -85,11 +85,11 @@ ## Remarks The contains all the objects for a particular . To access the of a , use the property. - The uses methods such as , , and to manage the items in the collection. + The uses methods such as , , and to manage the items in the collection. - Use the method to determine whether a particular table (specified by either index or name) is in the collection. + Use the method to determine whether a particular table (specified by either index or name) is in the collection. - To navigate from one table to another, use the or property of the to access its collection of objects. You can also use the property to navigate through the parent/child relationships of the `DataTables` in a particular collection. + To navigate from one table to another, use the or property of the to access its collection of objects. You can also use the property to navigate through the parent/child relationships of the `DataTables` in a particular collection. @@ -174,7 +174,7 @@ ## Examples - The following example adds three new objects to the using the method without arguments. + The following example adds three new objects to the using the method without arguments. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add2 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source1.vb" id="Snippet1"::: @@ -516,7 +516,7 @@ to test whether each table can be removed from a . If so, the method is called to remove the table. + The following example uses the to test whether each table can be removed from a . If so, the method is called to remove the table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.CanRemove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CanRemove/source.vb" id="Snippet1"::: @@ -571,7 +571,7 @@ method. + To remove a particular `DataTable` from the collection, use the method. @@ -758,9 +758,9 @@ object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). + You specify the name of the object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). - To get the index of a , use the method. + To get the index of a , use the method. > [!NOTE] > Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. @@ -830,12 +830,12 @@ object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). + You specify the name of the object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). > [!NOTE] > Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. - To get the index of a , use the method. + To get the index of a , use the method. @@ -969,9 +969,9 @@ method to determine the exact index of a given table. + Use the method to determine the exact index of a given table. - Before calling , you can test for the existence of a table (specified by either index or name) by using the method. + Before calling , you can test for the existence of a table (specified by either index or name) by using the method. @@ -1187,9 +1187,9 @@ This method returns -1 when two or more tables have the same name but different method to determine whether a table with a specific index exists. + Use the method to determine whether a table with a specific index exists. - If you have the name of a table, but not its index, use the method to return the index. + If you have the name of a table, but not its index, use the method to return the index. @@ -1257,7 +1257,7 @@ This method returns -1 when two or more tables have the same name but different ## Remarks If a name exists that matches the case of the search string, it is returned. Otherwise a case-insensitive search is performed, and if a name is found that matches this search, it is returned. - Use the method to determine whether a table with a specific name or index exists. + Use the method to determine whether a table with a specific name or index exists. @@ -1492,12 +1492,12 @@ This method returns -1 when two or more tables have the same name but different ## Remarks The event occurs when a table is successfully removed. - To determine whether a given table exists and can be removed before invoking , use the and the methods. + To determine whether a given table exists and can be removed before invoking , use the and the methods. ## Examples - The following example uses the method to test whether each table can be removed from a . If so, the method is called to remove the table. + The following example uses the method to test whether each table can be removed from a . If so, the method is called to remove the table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source.vb" id="Snippet1"::: @@ -1562,12 +1562,12 @@ This method returns -1 when two or more tables have the same name but different ## Remarks The event occurs when a table is successfully removed. - To determine whether a given table exists and can be removed before invoking , use the and the methods. + To determine whether a given table exists and can be removed before invoking , use the and the methods. ## Examples - The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. + The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: @@ -1628,12 +1628,12 @@ This method returns -1 when two or more tables have the same name but different ## Remarks The event occurs when a table is successfully removed. - To determine whether a given table exists and can be removed before invoking , use the and the methods. + To determine whether a given table exists and can be removed before invoking , use the and the methods. ## Examples - The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. + The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: @@ -1696,7 +1696,7 @@ This method returns -1 when two or more tables have the same name but different ## Examples - The following example uses the and methods to test whether a table exists with the index 10. If so, the method is called to remove the table. + The following example uses the and methods to test whether a table exists with the index 10. If so, the method is called to remove the table. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.RemoveAt/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/RemoveAt/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataTableExtensions.xml b/xml/System.Data/DataTableExtensions.xml index 8caab8c9e6b..3e3ab6e96ff 100644 --- a/xml/System.Data/DataTableExtensions.xml +++ b/xml/System.Data/DataTableExtensions.xml @@ -181,19 +181,19 @@ The following query operators, only, are supported in a query used to create : -- +- -- +- -- +- -- +- -- +- -- +- -- +- For more information and examples, see [Creating a DataView Object](/dotnet/framework/data/adonet/creating-a-dataview-object-linq-to-dataset). @@ -252,9 +252,9 @@ interface or the interface. The class does not implement either interface, so you must call the method to use the as a source in the `From` clause of a LINQ query. You can also obtain custom, domain-specific operators, such as , by returning an object. + Language-Integrated Query (LINQ) queries work on data sources that implement the interface or the interface. The class does not implement either interface, so you must call the method to use the as a source in the `From` clause of a LINQ query. You can also obtain custom, domain-specific operators, such as , by returning an object. - The enumerable object returned by the method is permanently bound to the that produced it. Multiple calls to the method will return multiple, independent queryable objects that are all bound to the source . + The enumerable object returned by the method is permanently bound to the that produced it. Multiple calls to the method will return multiple, independent queryable objects that are all bound to the source . @@ -337,9 +337,9 @@ ## Remarks The parameter `T` of the input parameter `source` can only be of type or a type derived from . - The input sequence can be any source, not only a query or a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. + The input sequence can be any source, not only a query or a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. - The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . + The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . When a **null** reference or nullable type with a value of **null** is found in a source , this method replaces the value in the destination with a value of . @@ -350,7 +350,7 @@ ## Examples - The following example queries the SalesOrderHeader table for orders after August 8, 2001, and uses the method to create a from that query. The is then bound to a , which acts as proxy for a . + The following example queries the SalesOrderHeader table for orders after August 8, 2001, and uses the method to create a from that query. The is then bound to a , which acts as proxy for a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DP LINQ to DataSet Examples/CS/Program.cs" id="Snippetcopytodatatable1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableExtensions/CopyToDataTableT/Module1.vb" id="Snippetcopytodatatable1"::: @@ -427,9 +427,9 @@ ## Remarks The parameter `T` of the input parameter `source` can only be of type , or a type derived from . - The input sequence can be any source, not only a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. + The input sequence can be any source, not only a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. - The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . + The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . When a **null** reference or nullable type with a value of **null** is found in a source , this method replaces the value in the destination with a value of . @@ -520,9 +520,9 @@ ## Remarks The parameter `T` of the input parameter `source` can only be of type , or a type derived from . - The input sequence can be any source, not only a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. + The input sequence can be any source, not only a query over a . Note that if the source sequence is a query, calling this operator will force immediate execution. Enumerating the source sequence can also cause exceptions to be thrown. - The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . + The schema of the destination table is based on the schema of the first row in the source sequence. The table metadata is extracted from the metadata and the table values from the column values of the . For a typed , types are not preserved. The data and schema are transferred, but the resulting rows of the output table will not be of the typed type. The and properties are not preserved during the copy from the source to the returned . When a **null** reference or nullable type with a value of **null** is found in a source , this method replaces the value in the destination with a value of . @@ -536,7 +536,7 @@ - The property is set to the caught exception. - The property is read after the delegate call returns. If the property is `true`, the source sequence continues to be enumerated and loaded into the data table. If the property is `false`, the original exception is thrown from the method. + The property is read after the delegate call returns. If the property is `true`, the source sequence continues to be enumerated and loaded into the data table. If the property is `false`, the original exception is thrown from the method. For more information, see [Creating a DataTable From a Query](/dotnet/framework/data/adonet/creating-a-datatable-from-a-query-linq-to-dataset). diff --git a/xml/System.Data/DataTableReader.xml b/xml/System.Data/DataTableReader.xml index a0dd0272fad..aa19f023bd5 100644 --- a/xml/System.Data/DataTableReader.xml +++ b/xml/System.Data/DataTableReader.xml @@ -60,7 +60,7 @@ The returned result set contains only the current version of each ; rows that are marked for deletion are skipped. - The `DataTableReader` provides a stable iterator; that is, the contents of the `DataTableReader` are not invalidated if the size of the underlying collection is modified during iteration. For example, if one or more rows in the collection are deleted or removed during iteration, the current position within the `DataTableReader` is maintained appropriately and it does not invalidate the iterator. + The `DataTableReader` provides a stable iterator; that is, the contents of the `DataTableReader` are not invalidated if the size of the underlying collection is modified during iteration. For example, if one or more rows in the collection are deleted or removed during iteration, the current position within the `DataTableReader` is maintained appropriately and it does not invalidate the iterator. ]]> @@ -372,7 +372,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must either already be a Boolean or coercible to a Boolean, or an exception is generated. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -438,7 +438,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a byte or coercible to a byte. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -582,7 +582,7 @@ ## Remarks No conversions are performed; therefore the data retrieved must already be a character or coercible to a character. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -725,7 +725,7 @@ method always returns the type of the underlying instead of a provider-specific type. + The method always returns the type of the underlying instead of a provider-specific type. @@ -796,7 +796,7 @@ Name: String ## Remarks No conversions are performed; therefore the data retrieved must already be a or coercible to a `DataTime`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -862,7 +862,7 @@ Name: String ## Remarks No conversions are performed; therefore the data retrieved must already be a or coercible to a `Decimal`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -928,7 +928,7 @@ Name: String ## Remarks No conversions are performed; therefore the data retrieved must already be a double-precision floating point number or must be coercible to a double-precision floating point number. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -991,18 +991,18 @@ Name: String ## Remarks Enumerators only allow for reading the data in the . Enumerators cannot be used to modify the underlying collection. - At first, the enumerator is positioned before the first element in the collection. At this position, calling throws an exception. Therefore, you must call `MoveNext` to advance the enumerator to the first element of the collection before reading the value of `Current`. + At first, the enumerator is positioned before the first element in the collection. At this position, calling throws an exception. Therefore, you must call `MoveNext` to advance the enumerator to the first element of the collection before reading the value of `Current`. - `Current` returns a , and returns the same object until either or is called. `MoveNext` sets `Current` to the next element. + `Current` returns a , and returns the same object until either or is called. `MoveNext` sets `Current` to the next element. - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling `MoveNext` returns false. If the last call to `MoveNext` returned `false`, calling `Current` throws an exception. In addition, because the provides forward-only access to its data, calling the method of the IEnumerator throws a . + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling `MoveNext` returns false. If the last call to `MoveNext` returned `false`, calling `Current` throws an exception. In addition, because the provides forward-only access to its data, calling the method of the IEnumerator throws a . - The provides a stable enumerator. This means that even if row deletions or additions occur within the underlying data, the enumerator returned by a call to is still valid. + The provides a stable enumerator. This means that even if row deletions or additions occur within the underlying data, the enumerator returned by a call to is still valid. ## Examples - The following example demonstrates the use of the method. This includes the behavior of the enumerator when rows are deleted from the underlying while the enumerator is active. + The following example demonstrates the use of the method. This includes the behavior of the enumerator when rows are deleted from the underlying while the enumerator is active. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetEnumerator/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetEnumerator/source.vb" id="Snippet1"::: @@ -1131,7 +1131,7 @@ Russ ## Remarks No conversions are performed; therefore the data retrieved must already be a single-precision floating point number or must be coercible to a single-precision floating point number. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1197,7 +1197,7 @@ Russ ## Remarks No conversions are performed; therefore the data retrieved must already be a or coercible to a `Guid`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1263,7 +1263,7 @@ Russ ## Remarks No conversions are performed; therefore, the data retrieved must already be an or coercible to an `Int16`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1329,7 +1329,7 @@ Russ ## Remarks No conversions are performed; therefore, the data retrieved must already be an or coercible to an `Int32`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1395,7 +1395,7 @@ Russ ## Remarks No conversions are performed; therefore, the data retrieved must already be an or coercible to an `Int64`. - Call to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1459,7 +1459,7 @@ Russ methods provide inverse functionality. That is, calling `GetOrdinal` on the return value of calling `GetName` should return the original parameter passed to `GetName`; the same applies to calling the procedures in the opposite order. + The `GetName` and methods provide inverse functionality. That is, calling `GetOrdinal` on the return value of calling `GetName` should return the original parameter passed to `GetName`; the same applies to calling the procedures in the opposite order. @@ -1595,7 +1595,7 @@ Russ always returns the type stored within the underlying , the value returned by calling the method always returns the same type as the type stored within the . When you work with the class, calling the method returns the same type as calling the method. + Because the always returns the type stored within the underlying , the value returned by calling the method always returns the same type as the type stored within the . When you work with the class, calling the method returns the same type as calling the method. ]]> @@ -1650,7 +1650,7 @@ Russ always returns the type stored within the underlying , the value returned by calling the method always returns data of the same type as the data stored within the . When you work with the class, calling the method returns the same value and type as calling the method. + Because the always returns the type stored within the underlying , the value returned by calling the method always returns data of the same type as the data stored within the . When you work with the class, calling the method returns the same value and type as calling the method. ]]> @@ -1706,7 +1706,7 @@ Russ always returns the data of the type stored within the underlying , the values returned by calling the method is always of the same types as the data stored within the . When you work with the class, calling the method returns the same values and types as calling the method. + Because the always returns the data of the type stored within the underlying , the values returned by calling the method is always of the same types as the data stored within the . When you work with the class, calling the method returns the same values and types as calling the method. ]]> @@ -1764,7 +1764,7 @@ Russ |-----------------------|-----------------| |ColumnName|The name of the column as it appears in the .| |ColumnOrdinal|The ordinal of the column| -|ColumnSize|-1 if the (or ) property of the cannot be determined or is not relevant; otherwise, 0 or a positive integer that contains the `MaxLength` value.| +|ColumnSize|-1 if the (or ) property of the cannot be determined or is not relevant; otherwise, 0 or a positive integer that contains the `MaxLength` value.| |NumericPrecision|If the column type is a numeric type, this is the maximum precision of the column. If the column type is not a numeric data type, this is a null value.| |NumericScale|If column data type has a scale component, return the number of digits to the right of the decimal point. Otherwise, return a null value.| |DataType|The underlying type of the column.| @@ -1847,7 +1847,7 @@ Russ to see if there are null values before calling this method. + Call to see if there are null values before calling this method. @@ -1911,12 +1911,12 @@ Russ to see if there are null values before calling this method, you do not have to do this. + Although you can call to see if there are null values before calling this method, you do not have to do this. ## Examples - The following example iterates through all the columns within the current row in a , displaying the contents of each column and the column name. Generally, if your intent is to work with all the columns within a row retrieved by a , consider using the method instead, because it is more efficient. + The following example iterates through all the columns within the current row in a , displaying the contents of each column and the column name. Generally, if your intent is to work with all the columns within a row retrieved by a , consider using the method instead, because it is more efficient. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetValue/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetValue/source.vb" id="Snippet1"::: @@ -2038,9 +2038,9 @@ Russ contains multiple result sets, you can examine the value of the `HasRows` property immediately after you call the method in order to determine whether the new result set contains rows. + The `HasRows` property returns information about the current result set. If the contains multiple result sets, you can examine the value of the `HasRows` property immediately after you call the method in order to determine whether the new result set contains rows. - Use the `HasRows` property to avoid the requirement to call the method of the if there are no rows within the current result set. + Use the `HasRows` property to avoid the requirement to call the method of the if there are no rows within the current result set. @@ -2100,7 +2100,7 @@ Russ is the only method and `IsClosed` and are the only properties that can be accessed after the has been closed. + is the only method and `IsClosed` and are the only properties that can be accessed after the has been closed. ]]> @@ -2153,7 +2153,7 @@ Russ , , and so on) to avoid raising an error. + Call this method to see if there are null column values before calling the typed get methods (for example, , , and so on) to avoid raising an error. @@ -2226,12 +2226,12 @@ Russ behaves identically to the method. + This overload for behaves identically to the method. ## Examples - The following example displays the contents of all the columns, in all the rows from the supplied . The code uses the method (the indexer, in Microsoft C#) to retrieve the value that is contained in each column. + The following example displays the contents of all the columns, in all the rows from the supplied . The code uses the method (the indexer, in Microsoft C#) to retrieve the value that is contained in each column. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.Item/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Item/source.vb" id="Snippet1"::: @@ -2292,7 +2292,7 @@ Russ This method is kana-width insensitive. - This overloaded version of corresponds to calling the method, and then subsequently calling the method. + This overloaded version of corresponds to calling the method, and then subsequently calling the method. diff --git a/xml/System.Data/DataView.xml b/xml/System.Data/DataView.xml index f983bb4f27b..e101f88ad17 100644 --- a/xml/System.Data/DataView.xml +++ b/xml/System.Data/DataView.xml @@ -126,11 +126,11 @@ ## Remarks A major function of the is to allow for data binding on both Windows Forms and Web Forms. - Additionally, a can be customized to present a subset of data from the . This capability lets you have two controls bound to the same , but that show different versions of the data. For example, one control might be bound to a that shows all the rows in the table, and a second might be configured to display only the rows that have been deleted from the . The also has a property. This returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . + Additionally, a can be customized to present a subset of data from the . This capability lets you have two controls bound to the same , but that show different versions of the data. For example, one control might be bound to a that shows all the rows in the table, and a second might be configured to display only the rows that have been deleted from the . The also has a property. This returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . - To create a filtered and sorted view of data, set the and properties. Then, use the property to return a single . + To create a filtered and sorted view of data, set the and properties. Then, use the property to return a single . - You can also add and delete from the set of rows using the and methods. When you use those methods, the property can set to specify that only deleted rows or new rows be displayed by the . + You can also add and delete from the set of rows using the and methods. When you use those methods, the property can set to specify that only deleted rows or new rows be displayed by the . > [!NOTE] > If you do not explicitly specify sort criteria for `DataView`, the `DataRowView` objects in `DataView` are sorted based on the index of DataView's corresponding `DataRow` in the `DataTable.Rows` `DataRowCollection`. @@ -140,7 +140,7 @@ ## Examples - The following example creates a single with one column and five rows. Two objects are created and the is set on each to show different views of the table data. The values are then printed. + The following example creates a single with one column and five rows. Two objects are created and the is set on each to show different views of the table data. The values are then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Overview/source.vb" id="Snippet1"::: @@ -392,7 +392,7 @@ method to return a new that has been added to the . + The following example uses the method to return a new that has been added to the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AddNew Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AddNew/source.vb" id="Snippet1"::: @@ -522,7 +522,7 @@ method before editing a row in a . + The following example invokes the method before editing a row in a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AllowEdit Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowEdit/source.vb" id="Snippet1"::: @@ -589,7 +589,7 @@ property to true before adding a new row with the method. + The following example sets the property to true before adding a new row with the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AllowNew Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowNew/source.vb" id="Snippet1"::: @@ -705,7 +705,7 @@ method ends the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to start the initialization of a component that is used on a form or used by another component. The method ends the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. ]]> @@ -755,7 +755,7 @@ in derived classes. Use the corresponding method to open the . + The method lets you manually close the in derived classes. Use the corresponding method to open the . This property is designed for internal use only. @@ -1020,12 +1020,12 @@ , its state changes to `DataViewRowState.Deleted`. You can roll back the deletion by calling on the . + After deleting a , its state changes to `DataViewRowState.Deleted`. You can roll back the deletion by calling on the . ## Examples - The following example uses the method to delete a row. + The following example uses the method to delete a row. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Delete/source.vb" id="Snippet1"::: @@ -1083,7 +1083,7 @@ and the underlying stop after this method is called. should be called for all objects. + Property change notifications between the and the underlying stop after this method is called. should be called for all objects. ]]> @@ -1136,7 +1136,7 @@ method starts the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. + The Visual Studio .NET design environment uses this method to end the initialization of a component that is used on a form or used by another component. The method starts the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. ]]> @@ -1249,7 +1249,7 @@ method to return the index of the row that contains the value in the sort key column that you want. + The following Visual Basic example uses the method to return the index of the row that contains the value in the sort key column that you want. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source.vb" id="Snippet1"::: @@ -1314,7 +1314,7 @@ method to return the index of a row that contains specified values in its sort key columns. + The following Visual Basic example uses the method to return the index of a row that contains specified values in its sort key columns. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source1.vb" id="Snippet1"::: @@ -1691,7 +1691,7 @@ is a "view" on a because it provides custom sorting and filtering of the data. The property can be queried to determine whether a has been opened by using the method. + A is a "view" on a because it provides custom sorting and filtering of the data. The property can be queried to determine whether a has been opened by using the method. This property is designed for internal use only. @@ -1905,7 +1905,7 @@ in derived classes. Use the corresponding method to close the . + The method lets you manually open the in derived classes. Use the corresponding method to close the . This property is designed for internal use only. @@ -2014,7 +2014,7 @@ value, specify the name of a column followed by an operator and a value to filter on. The value must be in quotation marks. For example: + To form a value, specify the name of a column followed by an operator and a value to filter on. The value must be in quotation marks. For example: "LastName = 'Smith'" @@ -2092,19 +2092,19 @@ method will have their value set to `Deleted`. Those rows added using the method will similarly have the property set to `Added`. + Only rows that have been deleted by using the method will have their value set to `Deleted`. Those rows added using the method will similarly have the property set to `Added`. > [!NOTE] -> Using the method of the class does not mean that a row will be marked as `Deleted`. Use the method instead to make sure that such rows can be viewed in the . +> Using the method of the class does not mean that a row will be marked as `Deleted`. Use the method instead to make sure that such rows can be viewed in the . - New rows will also be visible when the is set to `ModifiedCurrent` or `CurrentRows`. + New rows will also be visible when the is set to `ModifiedCurrent` or `CurrentRows`. - Deleted rows will also be visible when the is set to `ModifiedOriginal` and `OriginalRows`. + Deleted rows will also be visible when the is set to `ModifiedOriginal` and `OriginalRows`. ## Examples - The following example creates a with a single column, and then changes the data and sets the of the to display different row sets, depending on the . + The following example creates a with a single column, and then changes the data and sets the of the to display different row sets, depending on the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.RowStateFilter Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: @@ -2404,7 +2404,7 @@ . Instead, use the Clear method on the object returned by . + This member is an explicit interface member implementation. The use of this member is not supported and will cause a . Instead, use the Clear method on the object returned by . ]]> @@ -3861,7 +3861,7 @@ . Instead, use the Clear method on the object returned by . + This member is an explicit interface member implementation. The use of this member is not supported and will cause a . Instead, use the Clear method on the object returned by . ]]> @@ -4145,7 +4145,7 @@ also has a property which returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . + The also has a property which returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . You can only set the property if the current value is null. @@ -4175,7 +4175,7 @@ maintains the values of the following properties from the source : , , , and . Each column in the resulting contains an identical copy of all the corresponding properties in the underlying . + The returned maintains the values of the following properties from the source : , , , and . Each column in the resulting contains an identical copy of all the corresponding properties in the underlying . The instances in the returned `DataTable` will contain values that are consistent with CLR semantics. That is, for all data types besides user-defined types, the corresponding column values are copied by value. For user-defined data types, the column data is copied by reference. @@ -4517,7 +4517,7 @@ New table name: NewTable method if you have to retrieve distinct values in a subset of available columns, specifying a new name for the returned . If you do not need distinct rows or a subset of columns, see . + Use this overloaded version of the method if you have to retrieve distinct values in a subset of available columns, specifying a new name for the returned . If you do not need distinct rows or a subset of columns, see . diff --git a/xml/System.Data/DataViewManager.xml b/xml/System.Data/DataViewManager.xml index 1493d41bf85..25526265081 100644 --- a/xml/System.Data/DataViewManager.xml +++ b/xml/System.Data/DataViewManager.xml @@ -333,11 +333,11 @@ Gets or sets a value that is used for code persistence. A value that is used for code persistence. - directly. - + directly. + ]]> Managing DataViews @@ -590,11 +590,11 @@ The zero-based index in at which copying begins. Copies the elements of the to an , starting at a particular index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -641,11 +641,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -693,11 +693,11 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -744,11 +744,11 @@ For a description of this member, see . An object that can be used to synchronize access to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -797,11 +797,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -853,11 +853,11 @@ Adds an item to the . The position into which the new element was inserted. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -905,11 +905,11 @@ For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -962,11 +962,11 @@ if the is found in the ; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1018,11 +1018,11 @@ Determines the index of a specific item in the . The index of if found in the list; otherwise, -1. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1075,11 +1075,11 @@ The to insert into the . Inserts an item to the at the specified index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1127,11 +1127,11 @@ if the has a fixed size; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1178,11 +1178,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1240,11 +1240,11 @@ Gets or sets the element at the specified index. The element at the specified index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1295,11 +1295,11 @@ The to remove from the . Removes the first occurrence of a specific object from the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1350,11 +1350,11 @@ The zero-based index of the item to remove. Removes the item at the specified index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1405,11 +1405,11 @@ The to add to the indexes used for searching. Adds the to the indexes used for searching. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1458,11 +1458,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1509,11 +1509,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1560,11 +1560,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1611,11 +1611,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1668,11 +1668,11 @@ One of the values. Sorts the list based on a and a . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1726,11 +1726,11 @@ Returns the index of the row that has the given . The index of the row that has the given . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1777,11 +1777,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1832,11 +1832,11 @@ The to remove from the indexes used for searching. Removes the from the indexes used for searching. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1884,11 +1884,11 @@ Removes any sort applied using . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1935,11 +1935,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1993,11 +1993,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2044,11 +2044,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2095,11 +2095,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2146,11 +2146,11 @@ For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2202,11 +2202,11 @@ Returns the that represents the properties on each item used to bind data. The that represents the properties on each item used to bind data. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2258,11 +2258,11 @@ Returns the name of the list. The name of the list. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data/DataViewRowState.xml b/xml/System.Data/DataViewRowState.xml index 052a280bab1..4c294e4868c 100644 --- a/xml/System.Data/DataViewRowState.xml +++ b/xml/System.Data/DataViewRowState.xml @@ -72,12 +72,12 @@ You can use the Boolean operator Or with the values to get more than one version. - The uses in the method. + The uses in the method. ## Examples - In the following example is created with a single column. The data is changed, and the of the is set to display different row sets, depending on the . + In the following example is created with a single column. The data is changed, and the of the is set to display different row sets, depending on the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.RowStateFilter Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataViewSetting.xml b/xml/System.Data/DataViewSetting.xml index 7f36cf065be..5ba9a921072 100644 --- a/xml/System.Data/DataViewSetting.xml +++ b/xml/System.Data/DataViewSetting.xml @@ -251,7 +251,7 @@ is `DataViewRowState.CurrentRows`. + The default value of is `DataViewRowState.CurrentRows`. ]]> @@ -300,7 +300,7 @@ can have two defaults based on the value of property. If is null or empty (that is, the value is not explicitly specified), the in the is sorted on the position or ordinal of in the collection. The default, an empty string, causes a in to be sorted on the position or ordinal of in the collection. + can have two defaults based on the value of property. If is null or empty (that is, the value is not explicitly specified), the in the is sorted on the position or ordinal of in the collection. The default, an empty string, causes a in to be sorted on the position or ordinal of in the collection. ]]> diff --git a/xml/System.Data/DataViewSettingCollection.xml b/xml/System.Data/DataViewSettingCollection.xml index 16fb9a2794f..e767a076365 100644 --- a/xml/System.Data/DataViewSettingCollection.xml +++ b/xml/System.Data/DataViewSettingCollection.xml @@ -620,7 +620,7 @@ ## Remarks Derived classes can provide a synchronized version of the using the property. - Program code must always perform synchronized operations on the of the , not directly on the . This guarantees the correct operation of collections that are derived from other objects. Specifically, it maintains the correct synchronization with other threads that might be simultaneously modifying the . + Program code must always perform synchronized operations on the of the , not directly on the . This guarantees the correct operation of collections that are derived from other objects. Specifically, it maintains the correct synchronization with other threads that might be simultaneously modifying the . ]]> diff --git a/xml/System.Data/DeletedRowInaccessibleException.xml b/xml/System.Data/DeletedRowInaccessibleException.xml index bcbb0b0307e..735b0a184ea 100644 --- a/xml/System.Data/DeletedRowInaccessibleException.xml +++ b/xml/System.Data/DeletedRowInaccessibleException.xml @@ -60,7 +60,7 @@ , use the method of a class. As soon as you have deleted a row, any attempts to modify it will generate the . + To delete a , use the method of a class. As soon as you have deleted a row, any attempts to modify it will generate the . The is thrown when you use one of the following properties or methods that try to get or set the value of a deleted : @@ -68,9 +68,9 @@ - property -- method +- method - Use the of a class to determine whether a row has been deleted. If it has been deleted, you can use the field to retrieve it because deleted rows have no values available for the state. + Use the of a class to determine whether a row has been deleted. If it has been deleted, you can use the field to retrieve it because deleted rows have no values available for the state. ]]> @@ -132,7 +132,7 @@ of a class to determine whether a row has been deleted. + Use the of a class to determine whether a row has been deleted. ]]> @@ -188,7 +188,7 @@ of a class to determine whether a row has been deleted. + Use the of a class to determine whether a row has been deleted. ]]> @@ -301,7 +301,7 @@ of a class to determine whether a row has been deleted. + Use the of a class to determine whether a row has been deleted. ]]> diff --git a/xml/System.Data/EntityKey.xml b/xml/System.Data/EntityKey.xml index c91d2f4f727..fd61bbf115a 100644 --- a/xml/System.Data/EntityKey.xml +++ b/xml/System.Data/EntityKey.xml @@ -239,7 +239,7 @@ ## Remarks The class contains a copy of the values that make up the logical key that is specified for this type of entity. - The members of the each have a property name and a value in a , where the key is the property name and the value is the actual value of that property on the object. + The members of the each have a property name and a value in a , where the key is the property name and the value is the actual value of that property on the object. ]]> @@ -478,7 +478,7 @@ property to `true`. When you call the method, the Entity Framework assigns a permanent key and sets the property to `false`. + When a new entity is created, the Entity Framework defines temporary key and sets the property to `true`. When you call the method, the Entity Framework assigns a permanent key and sets the property to `false`. > [!NOTE] > Temporary keys are constructed automatically by the framework; they cannot be constructed directly by a user. @@ -491,7 +491,7 @@ In addition, temporary keys have no or key values, but permanent keys do. - When the method is called on an entity's and the entity transitions from the state to state, the Entity Framework automatically computes a new permanent key for the entity and synchronizes all temporary key references. + When the method is called on an entity's and the entity transitions from the state to state, the Entity Framework automatically computes a new permanent key for the entity and synchronizes all temporary key references. ]]> @@ -565,7 +565,7 @@ is used by Object Services when deserializing an . For more information, see [Serializing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738446(v=vs.100)). + is used by Object Services when deserializing an . For more information, see [Serializing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738446(v=vs.100)). ]]> @@ -611,7 +611,7 @@ is used by Object Services when deserializing an . For more information, see [Serializing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738446(v=vs.100)). + is used by Object Services when deserializing an . For more information, see [Serializing Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738446(v=vs.100)). ]]> @@ -655,7 +655,7 @@ In addition, temporary keys have no or key values, but permanent keys do. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -697,7 +697,7 @@ In addition, temporary keys have no or key values, but regular keys do. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> diff --git a/xml/System.Data/EntityKeyMember.xml b/xml/System.Data/EntityKeyMember.xml index ac5d817d52a..ccdfe1d79af 100644 --- a/xml/System.Data/EntityKeyMember.xml +++ b/xml/System.Data/EntityKeyMember.xml @@ -60,11 +60,11 @@ Initializes a new instance of the class. - @@ -146,11 +146,11 @@ Returns a string representation of the entity key. A string representation of the entity key. - method returns a string in the format "[*keyName*, *keyValue*]". - + method returns a string in the format "[*keyName*, *keyValue*]". + ]]> diff --git a/xml/System.Data/EntityState.xml b/xml/System.Data/EntityState.xml index 614d922e37a..4e4efd429a0 100644 --- a/xml/System.Data/EntityState.xml +++ b/xml/System.Data/EntityState.xml @@ -31,7 +31,7 @@ ## Remarks The object context must know the state of an object to save changes back to the data source. objects store information. The `SaveChanges` methods of the process entities that are attached to the context and update the data source depending on the of each object. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). - The state of objects inside an object context is managed by the . To find out the state of an object, call one of the following methods: , , or . The property of the defines the state of the object. + The state of objects inside an object context is managed by the . To find out the state of an object, call one of the following methods: , , or . The property of the defines the state of the object. ]]> diff --git a/xml/System.Data/EnumerableRowCollection.xml b/xml/System.Data/EnumerableRowCollection.xml index 8e18b527330..f5395ff9f33 100644 --- a/xml/System.Data/EnumerableRowCollection.xml +++ b/xml/System.Data/EnumerableRowCollection.xml @@ -55,13 +55,13 @@ Represents a collection of objects returned from a LINQ to DataSet query. This API supports the .NET infrastructure and is not intended to be used directly from your code. - provides an entry point so that the cast operation can be intercepted within an extension method. The derived generic class is actually used by .NET to contain the results of a query. - - This class cannot be instantiated. - + provides an entry point so that the cast operation can be intercepted within an extension method. The derived generic class is actually used by .NET to contain the results of a query. + + This class cannot be instantiated. + ]]> @@ -110,11 +110,11 @@ Returns an enumerator for the collection of objects. This API supports the .NET infrastructure and is not intended to be used directly from your code. An that can be used to traverse the collection of objects. - diff --git a/xml/System.Data/EnumerableRowCollectionExtensions.xml b/xml/System.Data/EnumerableRowCollectionExtensions.xml index a2e582d0ebb..895be9fea2e 100644 --- a/xml/System.Data/EnumerableRowCollectionExtensions.xml +++ b/xml/System.Data/EnumerableRowCollectionExtensions.xml @@ -57,13 +57,13 @@ Contains the extension methods for the data row collection classes. - class contains static extension methods that define the method and standard query operations for the and classes. - - This class cannot be inherited and cannot be instantiated. - + class contains static extension methods that define the method and standard query operations for the and classes. + + This class cannot be inherited and cannot be instantiated. + ]]> @@ -124,11 +124,11 @@ Converts the elements of an to the specified type. An that contains each element of the source sequence converted to the specified type. - @@ -211,11 +211,11 @@ Sorts the rows of a in ascending order according to the specified key. An whose elements are sorted by the specified key. - @@ -288,11 +288,11 @@ Sorts the rows of a in ascending order according to the specified key and comparer. An whose elements are sorted by the specified key and comparer. - @@ -373,11 +373,11 @@ Sorts the rows of a in descending order according to the specified key. An whose elements are sorted by the specified key. - @@ -450,11 +450,11 @@ Sorts the rows of a in descending order according to the specified key and comparer. An whose elements are sorted by the specified key and comparer. - @@ -525,13 +525,13 @@ Projects each element of an into a new form. An whose elements are the result of invoking the transform function on each element of . - @@ -609,13 +609,13 @@ Performs a secondary ordering of the rows of a in ascending order according to the specified key. An whose elements are sorted by the specified key. - operation requires an existing primary sorting operation using . - - This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. - + operation requires an existing primary sorting operation using . + + This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + ]]> @@ -688,13 +688,13 @@ Performs a secondary ordering of the rows of a in ascending order according to the specified key and comparer. An whose elements are sorted by the specified key and comparer. - operation requires an existing primary sorting operation using . - - This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. - + operation requires an existing primary sorting operation using . + + This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + ]]> @@ -775,13 +775,13 @@ Performs a secondary ordering of the rows of a in descending order according to the specified key. An whose elements are sorted by the specified key. - operation requires an existing primary sorting operation using . - - This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. - + operation requires an existing primary sorting operation using . + + This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + ]]> @@ -854,13 +854,13 @@ Performs a secondary ordering of the rows of a in descending order according to the specified key and comparer. An whose elements are sorted by the specified key and comparer. - operation requires an existing primary sorting operation using . - - This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. - + operation requires an existing primary sorting operation using . + + This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + ]]> @@ -922,11 +922,11 @@ Filters a sequence of rows based on the specified predicate. An that contains rows from the input sequence that satisfy the condition. - diff --git a/xml/System.Data/EnumerableRowCollection`1.xml b/xml/System.Data/EnumerableRowCollection`1.xml index 52814eed0dd..7b81e4a104e 100644 --- a/xml/System.Data/EnumerableRowCollection`1.xml +++ b/xml/System.Data/EnumerableRowCollection`1.xml @@ -69,13 +69,13 @@ The type of objects in the source sequence, typically . Represents a collection of objects returned from a query. - is used to contain the results of a LINQ to DataSet query. - - An cannot be directly instantiated because there are no public constructors for this class. - + is used to contain the results of a LINQ to DataSet query. + + An cannot be directly instantiated because there are no public constructors for this class. + ]]> @@ -125,13 +125,13 @@ Returns an enumerator for the collection of contained row objects. A strongly-typed that can be used to traverse the collection of objects. - . - - This method cannot be overridden. - + . + + This method cannot be overridden. + ]]> @@ -184,13 +184,13 @@ Returns an enumerator for the collection of objects. An that can be used to traverse the collection of objects. - method. - - This method cannot be overridden. - + method. + + This method cannot be overridden. + ]]> diff --git a/xml/System.Data/ForeignKeyConstraint.xml b/xml/System.Data/ForeignKeyConstraint.xml index 6ff8070cc1e..f62e1b488cf 100644 --- a/xml/System.Data/ForeignKeyConstraint.xml +++ b/xml/System.Data/ForeignKeyConstraint.xml @@ -90,7 +90,7 @@ Constraints are not enforced unless the property is set to `true`. - The is enforced whenever a object's method is invoked. + The is enforced whenever a object's method is invoked. @@ -590,12 +590,12 @@ or are not final until the `AcceptChanges` method is invoked. At that point, the determines the course of action on any values that have been changed or deleted. + Changes to a or are not final until the `AcceptChanges` method is invoked. At that point, the determines the course of action on any values that have been changed or deleted. ## Examples - The following example creates a , sets its , and adds the constraint to a object's . + The following example creates a , sets its , and adds the constraint to a object's . :::code language="vb" source="~/snippets/visualbasic/System.Data/ForeignKeyConstraint/AcceptRejectRule/source.vb" id="Snippet1"::: @@ -722,7 +722,7 @@ determines what will happen in the columns of the child table (or tables). If the rule is set to `Cascade`, child rows will be deleted. + When a row is deleted from a parent table, the determines what will happen in the columns of the child table (or tables). If the rule is set to `Cascade`, child rows will be deleted. If set to `SetNull`, a `DBNull` will be placed in the appropriate columns of the affected rows. Depending on your data source, a null value may or may not be permitted in a column. For example, SQL Server allows multiple null values to be found in a primary key column, even if they are not unique. In a , however, if a object's property is set to `true`, multiple null values are not allowed in primary key columns. @@ -795,7 +795,7 @@ and checks it against other collection members with the method before adding it to a . + The following example creates a new and checks it against other collection members with the method before adding it to a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ForeignKeyConstraint.Equals Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ForeignKeyConstraint/Equals/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/IColumnMapping.xml b/xml/System.Data/IColumnMapping.xml index 685fd0070cc..fe42316a38b 100644 --- a/xml/System.Data/IColumnMapping.xml +++ b/xml/System.Data/IColumnMapping.xml @@ -51,7 +51,7 @@ An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. + Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. diff --git a/xml/System.Data/IColumnMappingCollection.xml b/xml/System.Data/IColumnMappingCollection.xml index fb87a6f8a1b..de07851761a 100644 --- a/xml/System.Data/IColumnMappingCollection.xml +++ b/xml/System.Data/IColumnMappingCollection.xml @@ -55,36 +55,36 @@ Contains a collection of DataColumnMapping objects, and is implemented by the , which is used in common by .NET data providers. - interface enables an inheriting class to implement a ColumnMapping collection. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and defines two additional overloads of . - - - -## Examples - The following example uses an instance of the derived class, , to several objects to its collection, and then displays a list of those mapped source tables. This example assumes that a has already been created. - + interface enables an inheriting class to implement a ColumnMapping collection. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and defines two additional overloads of . + + + +## Examples + The following example uses an instance of the derived class, , to several objects to its collection, and then displays a list of those mapped source tables. This example assumes that a has already been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/Overview/source.vb" id="Snippet1"::: + ]]> - When you inherit from the interface, you should implement the following constructor: - - Item - - Description - - ColumnMappingCollection() - - Creates an empty ColumnMappingCollection class. - + When you inherit from the interface, you should implement the following constructor: + + Item + + Description + + ColumnMappingCollection() + + Creates an empty ColumnMappingCollection class. + @@ -276,14 +276,14 @@ Gets the location of the object with the specified source column name. The name is case-sensitive. The zero-based location of the object with the specified source column name. - , with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. - + , with the given source column name within a collection. If the exists, the example displays the name and the index of the mapping. If the mapping does not exist, the example displays an error. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> @@ -377,14 +377,14 @@ The case-sensitive name. Removes the object with the specified name from the collection. - , with the given `SourceColumn` name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. - + , with the given `SourceColumn` name within a collection. If the exists, the mapping is removed. This example assumes that a collection has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMappingCollection.RemoveAt1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMappingCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> A object does not exist with the specified name. diff --git a/xml/System.Data/IDataAdapter.xml b/xml/System.Data/IDataAdapter.xml index a2fb197cf2b..623550f6c8f 100644 --- a/xml/System.Data/IDataAdapter.xml +++ b/xml/System.Data/IDataAdapter.xml @@ -53,7 +53,7 @@ An application does not create an instance of the interface directly, but implements an instance of a class that inherits . - Classes that inherit must implement the inherited members, and they typically define additional members to add provider-specific functionality. For example, the interface defines a method that takes a as a parameter. In turn, the class inherits the method and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. + Classes that inherit must implement the inherited members, and they typically define additional members to add provider-specific functionality. For example, the interface defines a method that takes a as a parameter. In turn, the class inherits the method and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. @@ -141,20 +141,20 @@ retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation usually creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation usually creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). If the encounters duplicate columns while populating a , it generates names for the successive columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are put in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the , each result set is put in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Applications should use caution when using column and table names to ensure that conflicts with these naming patterns do not occur. When the SELECT statement that is used to populate the returns multiple results, such as a batch SQL statement, if one of the results contains an error, all successive results are skipped and not added to the . - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. +> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. ]]> @@ -216,23 +216,23 @@ method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - A operation adds a to the destination . It then adds columns to the of the and configures the following properties if they exist at the data source: + A operation adds a to the destination . It then adds columns to the of the and configures the following properties if they exist at the data source: -- +- -- . You must set and separately. +- . You must set and separately. -- +- -- +- -- +- - also configures the and properties according to the following rules: + also configures the and properties according to the following rules: -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if all the unique columns are non-nullable. If any of the columns are nullable, a is added to the , but the property is not set. @@ -244,7 +244,7 @@ If the encounters duplicate columns while populating a , it generates names for the successive columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are put in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the , each result set is put in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Applications should use caution when using column and table names to ensure that conflicts with these naming patterns do not occur. - returns no rows. Use the method to add rows to a . + returns no rows. Use the method to add rows to a . ]]> @@ -461,7 +461,7 @@ private static void GetParameters(string connectionString) uses only the mappings for the source table named "Table". All SELECT, INSERT, DELETE, and UPDATE statements returning data must do so using consistent column naming. The column names returned in the records must be unique, otherwise columns with duplicate names overwrite previous data. On , only the table mapped to the source table named "Table" will have its changes reconciled. + The uses only the mappings for the source table named "Table". All SELECT, INSERT, DELETE, and UPDATE statements returning data must do so using consistent column naming. The column names returned in the records must be unique, otherwise columns with duplicate names overwrite previous data. On , only the table mapped to the source table named "Table" will have its changes reconciled. ]]> @@ -520,21 +520,21 @@ private static void GetParameters(string connectionString) method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, because of the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, because of the ordering of the rows in the . - Be aware that these statements are not performed as a batch process; each row is updated individually. An application can call the method if you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + Be aware that these statements are not performed as a batch process; each row is updated individually. An application can call the method if you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then updates the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then updates the row using the value of the property. Any additional rows returned are ignored. - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - When using , the order of execution is as follows: + When using , the order of execution is as follows: 1. The values in the are moved to the parameter values. -2. The event is raised. +2. The event is raised. 3. The command executes. @@ -542,9 +542,9 @@ private static void GetParameters(string connectionString) 5. If there are output parameters, they are put in the . -6. The event is raised. +6. The event is raised. -7. is called. +7. is called. Each command associated with the usually has a parameter collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. @@ -561,12 +561,12 @@ private static void GetParameters(string connectionString) The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the `Original`, `Current`, or `Proposed` version of the column value. This capability is frequently used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . ## Examples - The following example uses the derived class, , to the data source. This example assumes that you have created an and a . + The following example uses the derived class, , to the data source. This example assumes that you have created an and a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataAdapter.IDataAdapter.Update Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataAdapter/Update/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/IDataParameter.xml b/xml/System.Data/IDataParameter.xml index 78cb8f05a8c..53e17b79a35 100644 --- a/xml/System.Data/IDataParameter.xml +++ b/xml/System.Data/IDataParameter.xml @@ -145,7 +145,7 @@ are linked. Therefore, setting the changes the PrvDbType to a supporting PrvDbType. + The PrvDbType (where Prv represents the provider-specific prefix) and are linked. Therefore, setting the changes the PrvDbType to a supporting PrvDbType. For a list of the supported data types, see the appropriate .NET Framework data provider PrvDbType member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). @@ -319,7 +319,7 @@ ## Remarks - The is specified in the form \@*paramname*. You must set before executing a command that relies on parameters. + The is specified in the form \@*paramname*. You must set before executing a command that relies on parameters. @@ -435,7 +435,7 @@ during the to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the and . This property is set to the version of the used by the property, or the method of the object. + This property is used by the during the to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the and . This property is set to the version of the used by the property, or the method of the object. @@ -507,7 +507,7 @@ If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider attempts to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - The property is overwritten by . + The property is overwritten by . diff --git a/xml/System.Data/IDataParameterCollection.xml b/xml/System.Data/IDataParameterCollection.xml index 258b49e8d9f..46d6c753b3d 100644 --- a/xml/System.Data/IDataParameterCollection.xml +++ b/xml/System.Data/IDataParameterCollection.xml @@ -56,28 +56,28 @@ Collects all parameters relevant to a Command object and their mappings to columns, and is implemented by .NET data providers that access data sources. - interface allows an inheriting class to implement a Parameter collection. For more information about Parameter classes, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines one implementation of the method. In turn, the class inherits this method, and defines two additional overloads of `RemoveAt`. - + interface allows an inheriting class to implement a Parameter collection. For more information about Parameter classes, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines one implementation of the method. In turn, the class inherits this method, and defines two additional overloads of `RemoveAt`. + ]]> - When you inherit from the interface, you should implement the following constructor. - - Item - - Description - - PrvParameterCollection() - - Creates an empty PrvParameterCollection class. - + When you inherit from the interface, you should implement the following constructor. + + Item + + Description + + PrvParameterCollection() + + Creates an empty PrvParameterCollection class. + diff --git a/xml/System.Data/IDataReader.xml b/xml/System.Data/IDataReader.xml index 0ff5dad117f..d8897e31747 100644 --- a/xml/System.Data/IDataReader.xml +++ b/xml/System.Data/IDataReader.xml @@ -125,7 +125,7 @@ method when you are through using the to use the associated for any other purpose. + You must explicitly call the method when you are through using the to use the associated for any other purpose. ]]> @@ -229,14 +229,14 @@ Returns if the executed command returned no resultset, o method for the .NET Framework Data Provider for OLE DB maps to the OLE DB IColumnsRowset::GetColumnsRowset method, while implementations for other .NET Framework data providers do not use an OLE DB provider layer. The order in which returns metadata about each column in a table, and the DataReader columns that are returned, vary depending on which data provider you use. The following table lists data providers and members that implement . + The implementation of method for the .NET Framework Data Provider for OLE DB maps to the OLE DB IColumnsRowset::GetColumnsRowset method, while implementations for other .NET Framework data providers do not use an OLE DB provider layer. The order in which returns metadata about each column in a table, and the DataReader columns that are returned, vary depending on which data provider you use. The following table lists data providers and members that implement . |Data Provider|Member| |-------------------|------------| -|.NET Data Provider for ODBC|.| -|.NET Data Provider for OLE DB|.| -|.NET Data Provider for Oracle|.| -|.NET Data Provider for SQL Server|.| +|.NET Data Provider for ODBC|.| +|.NET Data Provider for OLE DB|.| +|.NET Data Provider for Oracle|.| +|.NET Data Provider for SQL Server|.| ]]> @@ -288,7 +288,7 @@ Returns if the executed command returned no resultset, o and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> @@ -397,9 +397,9 @@ Returns if the executed command returned no resultset, o is prior to the first record. Therefore you must call to begin accessing any data. + The default position of the is prior to the first record. Therefore you must call to begin accessing any data. - While the data reader is in use, the associated connection is busy serving the . This is the case until is called. + While the data reader is in use, the associated connection is busy serving the . This is the case until is called. @@ -459,7 +459,7 @@ Returns if the executed command returned no resultset, o ## Remarks The property is not set until all rows are read and you close the . - and are the only properties that you can call after the is closed. + and are the only properties that you can call after the is closed. ]]> diff --git a/xml/System.Data/IDataRecord.xml b/xml/System.Data/IDataRecord.xml index c07ffa051b4..310628f022c 100644 --- a/xml/System.Data/IDataRecord.xml +++ b/xml/System.Data/IDataRecord.xml @@ -149,7 +149,7 @@ method), returns -1. + After executing a query that does not return rows (for example, using the method), returns -1. ]]> @@ -315,9 +315,9 @@ returns the number of available bytes in the field. Frequently this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. + returns the number of available bytes in the field. Frequently this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. - If you pass a buffer that is `null`, returns the length of the row in bytes. + If you pass a buffer that is `null`, returns the length of the row in bytes. No conversions are performed; therefore the data retrieved must already be a byte array. @@ -431,7 +431,7 @@ returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the exact length of the field if `GetChars` has already been used to obtain characters from the field. + returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the exact length of the field if `GetChars` has already been used to obtain characters from the field. If you pass a buffer that is `null`, `GetChars` returns the length of the field in characters. @@ -1093,7 +1093,7 @@ ## Examples - The following example demonstrates how to use the inherited method. + The following example demonstrates how to use the inherited method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader.GetOrdinal/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataRecord/GetOrdinal/source.vb" id="Snippet1"::: @@ -1246,7 +1246,7 @@ method provides an efficient means for retrieving all columns, instead of retrieving each column individually. + For most applications, the method provides an efficient means for retrieving all columns, instead of retrieving each column individually. You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns that are contained in the resulting row. @@ -1303,7 +1303,7 @@ , , and so on) to avoid raising an error. + Call this method to see if there are null column values before calling the typed get methods (for example, , , and so on) to avoid raising an error. ]]> diff --git a/xml/System.Data/IDbCommand.xml b/xml/System.Data/IDbCommand.xml index c2b4f23de59..5bb4cca8066 100644 --- a/xml/System.Data/IDbCommand.xml +++ b/xml/System.Data/IDbCommand.xml @@ -56,7 +56,7 @@ An application does not create an instance of the interface directly, but creates an instance of a class that implements the interface. - Classes that implement must implement all its members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and also defines the method. + Classes that implement must implement all its members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and also defines the method. @@ -413,7 +413,7 @@ , a .NET Framework data provider implements a strongly-typed version of . + When inheriting from , a .NET Framework data provider implements a strongly-typed version of . ]]> @@ -464,9 +464,9 @@ to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. + You can use the to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. - Although the does not return any rows, any output parameters or return values mapped to parameters are populated with data. + Although the does not return any rows, any output parameters or return values mapped to parameters are populated with data. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. @@ -589,14 +589,14 @@ method of the property. + The caller must call the method of the property. - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . > [!NOTE] > Use to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. - While the is in use, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the DataReader is called. If the DataReader is created with set to `CloseConnection`, closing the DataReader closes the connection automatically. + While the is in use, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the DataReader is called. If the DataReader is created with set to `CloseConnection`, closing the DataReader closes the connection automatically. ]]> @@ -648,9 +648,9 @@ method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value using the data returned by an . + Use the method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value using the data returned by an . - A typical query can be formatted as in the following C# example: + A typical query can be formatted as in the following C# example: ``` CommandText = "select count(*) as NumberOfRegions from region"; @@ -662,7 +662,7 @@ Int32 count = (int) ExecuteScalar(); ## Examples - The following example creates an instance of the derived class, , and then executes it using . The example is passed a string that is a Transact-SQL statement that returns an aggregate result, and a string to use to connect to the data source. + The following example creates an instance of the derived class, , and then executes it using . The example is passed a string that is a Transact-SQL statement that returns an aggregate result, and a string to use to connect to the data source. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteScalar/CS/mysample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: @@ -769,7 +769,7 @@ Int32 count = (int) ExecuteScalar(); property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may result in a no-op. The server automatically caches plans for reuse as necessary; therefore, there is no need to call this method directly in your client application. + If the property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may result in a no-op. The server automatically caches plans for reuse as necessary; therefore, there is no need to call this method directly in your client application. diff --git a/xml/System.Data/IDbConnection.xml b/xml/System.Data/IDbConnection.xml index 08bbe61e56e..cb44f6b312f 100644 --- a/xml/System.Data/IDbConnection.xml +++ b/xml/System.Data/IDbConnection.xml @@ -61,7 +61,7 @@ ## Examples - The following example creates instances of the derived classes, and . The is opened and set as the for the . The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is a Transact-SQL INSERT statement. + The following example creates instances of the derived classes, and . The is opened and set as the for the . The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is a Transact-SQL INSERT statement. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbConnection/Overview/source.vb" id="Snippet1"::: @@ -144,7 +144,7 @@ or methods. + Once the transaction has completed, you must explicitly commit or roll back the transaction by using the or methods. ]]> @@ -198,7 +198,7 @@ or methods. + Once the transaction has completed, you must explicitly commit or roll back the transaction using the or methods. ]]> @@ -294,7 +294,7 @@ method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. + The method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled. An application can call `Close` more than one time without generating an exception. @@ -352,7 +352,7 @@ ## Examples - The following example creates an instance of a derived class, , sets its , and displays its . + The following example creates an instance of a derived class, , sets its , and displays its . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbConnection.ConnectionString Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbConnection/ConnectionString/source.vb" id="Snippet1"::: @@ -405,7 +405,7 @@ because it would cause the connection attempt to wait indefinitely. + A value of 0 indicates no limit to the wait time, rather than no wait time, and should be avoided in a because it would cause the connection attempt to wait indefinitely. ]]> @@ -499,7 +499,7 @@ method or by passing an SQL statement using one of the Execute methods. (Initially the database is set by means of the connection string.) If you change the current database using an SQL statement or the `ChangeDatabase` method, an informational message is sent and then the property is updated. + The `Database` property can be dynamically updated by using the method or by passing an SQL statement using one of the Execute methods. (Initially the database is set by means of the connection string.) If you change the current database using an SQL statement or the `ChangeDatabase` method, an informational message is sent and then the property is updated. ]]> @@ -604,7 +604,7 @@ ## Examples - The following example creates an instance of a derived class, , sets its , and displays its . + The following example creates an instance of a derived class, , sets its , and displays its . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbConnection.ConnectionString Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbConnection/ConnectionString/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/IDbDataAdapter.xml b/xml/System.Data/IDbDataAdapter.xml index db04dfe62a2..df04abb0d13 100644 --- a/xml/System.Data/IDbDataAdapter.xml +++ b/xml/System.Data/IDbDataAdapter.xml @@ -55,7 +55,7 @@ An application does not create an instance of the interface directly, but creates an instance of a class that inherits and . - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property, and the interface defines a method that takes a as a parameter. In turn, the class inherits the property and the method, and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property, and the interface defines a method that takes a as a parameter. In turn, the class inherits the property and the method, and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. @@ -140,14 +140,14 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. ## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.DeleteCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: @@ -200,9 +200,9 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. > [!NOTE] > If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. @@ -210,7 +210,7 @@ ## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.InsertCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: @@ -263,14 +263,14 @@ is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - If the does not return any rows, no tables are added to the , and no exception is raised. + If the does not return any rows, no tables are added to the , and no exception is raised. ## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.SelectCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: @@ -323,9 +323,9 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. > [!NOTE] > If execution of this command returns rows, these rows are added to the . @@ -333,7 +333,7 @@ ## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.UpdateCommand Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/IDbTransaction.xml b/xml/System.Data/IDbTransaction.xml index 55e98e18dcb..616e0142f05 100644 --- a/xml/System.Data/IDbTransaction.xml +++ b/xml/System.Data/IDbTransaction.xml @@ -49,23 +49,23 @@ Represents a transaction to be performed at a data source, and is implemented by .NET data providers that access relational databases. - interface allows an inheriting class to implement a Transaction class, which represents the transaction to be performed at a data source. For more information about Transaction classes, see [Transactions and Concurrency](/dotnet/framework/data/adonet/transactions-and-concurrency). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this property, and also defines the method. - - - -## Examples - The following example creates instances of the derived classes, and . It also demonstrates how to use the , , and methods. - + interface allows an inheriting class to implement a Transaction class, which represents the transaction to be performed at a data source. For more information about Transaction classes, see [Transactions and Concurrency](/dotnet/framework/data/adonet/transactions-and-concurrency). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this property, and also defines the method. + + + +## Examples + The following example creates instances of the derived classes, and . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> @@ -114,21 +114,21 @@ Commits the database transaction. - and a . It also demonstrates how to use the , , and methods. - + and a . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. @@ -177,11 +177,11 @@ Specifies the Connection object to associate with the transaction. The Connection object to associate with the transaction. - @@ -227,11 +227,11 @@ Specifies the for this transaction. The for this transaction. The default is . - applies to the entire transaction. - + applies to the entire transaction. + ]]> @@ -277,26 +277,26 @@ Rolls back a transaction from a pending state. - has been called, but before is called). - - - -## Examples - The following example creates instances of the derived classes, and a . It also demonstrates how to use the , , and methods. - + has been called, but before is called). + + + +## Examples + The following example creates instances of the derived classes, and a . It also demonstrates how to use the , , and methods. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.BeginTransaction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbTransaction/Overview/source.vb" id="Snippet1"::: + ]]> An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - + The transaction has already been committed or rolled back. + + -or- + The connection is broken. When overriding in a derived class, be sure to call the base class's method. diff --git a/xml/System.Data/ITableMapping.xml b/xml/System.Data/ITableMapping.xml index 921110886fa..77a1938beb6 100644 --- a/xml/System.Data/ITableMapping.xml +++ b/xml/System.Data/ITableMapping.xml @@ -51,7 +51,7 @@ An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. @@ -130,7 +130,7 @@ , sets some of its properties, and copies its to an array. This example assumes that a has been created. + The following example creates an instance of the derived class, , sets some of its properties, and copies its to an array. This example assumes that a has been created. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.ColumnMappings Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/ColumnMappings/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/ITableMappingCollection.xml b/xml/System.Data/ITableMappingCollection.xml index 5b5660ad81f..324b170af78 100644 --- a/xml/System.Data/ITableMappingCollection.xml +++ b/xml/System.Data/ITableMappingCollection.xml @@ -55,36 +55,36 @@ Contains a collection of TableMapping objects, and is implemented by the , which is used in common by .NET data providers. - interface allows an inheriting class to implement a TableMapping collection. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines one implementation of the method. In turn, the class inherits this method, and defines two additional overloads of . - - - -## Examples - The following example creates an instance of the derived class, , and adds it to a collection. It then informs the user that the mapping was added to the collection. - + interface allows an inheriting class to implement a TableMapping collection. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines one implementation of the method. In turn, the class inherits this method, and defines two additional overloads of . + + + +## Examples + The following example creates an instance of the derived class, , and adds it to a collection. It then informs the user that the mapping was added to the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: + ]]> - When you inherit from the interface, you should implement the following constructor: - - Item - - Description - - PrvTableMappingCollection() - - Creates an empty PrvTableMappingCollection class. - + When you inherit from the interface, you should implement the following constructor: + + Item + + Description + + PrvTableMappingCollection() + + Creates an empty PrvTableMappingCollection class. + diff --git a/xml/System.Data/InvalidConstraintException.xml b/xml/System.Data/InvalidConstraintException.xml index 1cef386c67f..311d85631ec 100644 --- a/xml/System.Data/InvalidConstraintException.xml +++ b/xml/System.Data/InvalidConstraintException.xml @@ -57,19 +57,19 @@ Represents the exception that is thrown when incorrectly trying to create or access a relation. - is thrown when incorrectly invoking the following methods while trying to create or access a relation. - -- - -- - -- - - If you call , the may be thrown if a relation cannot be created based on the values supplied in the parameters. If you call , the may be thrown if a is enforced on the . If you call , the may be thrown if the columns have different data types or the tables do not belong to the same . - + is thrown when incorrectly invoking the following methods while trying to create or access a relation. + +- + +- + +- + + If you call , the may be thrown if a relation cannot be created based on the values supplied in the parameters. If you call , the may be thrown if a is enforced on the . If you call , the may be thrown if the columns have different data types or the tables do not belong to the same . + ]]> diff --git a/xml/System.Data/MappingType.xml b/xml/System.Data/MappingType.xml index 727a58a8c97..7acea97b747 100644 --- a/xml/System.Data/MappingType.xml +++ b/xml/System.Data/MappingType.xml @@ -55,7 +55,7 @@ enumeration is used when getting or setting the property of the . The property determines how a column's values will be written when the method is called on a to write the data and schema out as an XML document. + The enumeration is used when getting or setting the property of the . The property determines how a column's values will be written when the method is called on a to write the data and schema out as an XML document. diff --git a/xml/System.Data/MissingMappingAction.xml b/xml/System.Data/MissingMappingAction.xml index 88816e9fdc3..c0478c91d1d 100644 --- a/xml/System.Data/MissingMappingAction.xml +++ b/xml/System.Data/MissingMappingAction.xml @@ -45,11 +45,11 @@ Determines the action that occurs when a mapping is missing from a source table or a source column. - values are used as arguments in the method, and the method. - + values are used as arguments in the method, and the method. + ]]> diff --git a/xml/System.Data/MissingPrimaryKeyException.xml b/xml/System.Data/MissingPrimaryKeyException.xml index 8c905220f48..48d05f57502 100644 --- a/xml/System.Data/MissingPrimaryKeyException.xml +++ b/xml/System.Data/MissingPrimaryKeyException.xml @@ -57,15 +57,15 @@ Represents the exception that is thrown when you try to access a row in a table that has no primary key. - is thrown when invoking the following methods to access a row in a table that has no primary key. - -- - -- - + is thrown when invoking the following methods to access a row in a table that has no primary key. + +- + +- + ]]> diff --git a/xml/System.Data/NoNullAllowedException.xml b/xml/System.Data/NoNullAllowedException.xml index 0d511dd4935..8cb78c9f525 100644 --- a/xml/System.Data/NoNullAllowedException.xml +++ b/xml/System.Data/NoNullAllowedException.xml @@ -57,19 +57,19 @@ Represents the exception that is thrown when you try to insert a null value into a column where is set to . - is thrown when invoking the following methods or properties when you try to insert a null value into a column where is set to `false`. - -- - -- - -- - -- - + is thrown when invoking the following methods or properties when you try to insert a null value into a column where is set to `false`. + +- + +- + +- + +- + ]]> diff --git a/xml/System.Data/OperationAbortedException.xml b/xml/System.Data/OperationAbortedException.xml index 320704004fc..260337f80a8 100644 --- a/xml/System.Data/OperationAbortedException.xml +++ b/xml/System.Data/OperationAbortedException.xml @@ -34,11 +34,11 @@ This exception is thrown when an ongoing operation is aborted by the user. - event sets the **Abort** property to `true` in the object passed to the handler, the method stops sending rows to the server and throws an . - + event sets the **Abort** property to `true` in the object passed to the handler, the method stops sending rows to the server and throws an . + ]]> diff --git a/xml/System.Data/OrderedEnumerableRowCollection`1.xml b/xml/System.Data/OrderedEnumerableRowCollection`1.xml index 1526e2312fd..d946850befd 100644 --- a/xml/System.Data/OrderedEnumerableRowCollection`1.xml +++ b/xml/System.Data/OrderedEnumerableRowCollection`1.xml @@ -64,13 +64,13 @@ The type of objects in the source sequence, typically . Represents a collection of ordered objects returned from a query. - is used to contain the results of a LINQ to DataSet query that returns an ordered sequence of rows. This maintains a state of call LINQ operators for the originating query, and this state is used to construct the predicate and sorting expressions for any subsequent . - - An cannot be directly instantiated because there are no public constructors for this class. - + is used to contain the results of a LINQ to DataSet query that returns an ordered sequence of rows. This maintains a state of call LINQ operators for the originating query, and this state is used to construct the predicate and sorting expressions for any subsequent . + + An cannot be directly instantiated because there are no public constructors for this class. + ]]> diff --git a/xml/System.Data/ReadOnlyException.xml b/xml/System.Data/ReadOnlyException.xml index 1e296dd6ab1..da0f98d335c 100644 --- a/xml/System.Data/ReadOnlyException.xml +++ b/xml/System.Data/ReadOnlyException.xml @@ -57,15 +57,15 @@ Represents the exception that is thrown when you try to change the value of a read-only column. - is thrown when you invoke the following methods or properties when you are trying to change the value of a read-only column. - -- - -- - + is thrown when you invoke the following methods or properties when you are trying to change the value of a read-only column. + +- + +- + ]]> diff --git a/xml/System.Data/RowNotInTableException.xml b/xml/System.Data/RowNotInTableException.xml index d83bfbebb28..d84a2252b7a 100644 --- a/xml/System.Data/RowNotInTableException.xml +++ b/xml/System.Data/RowNotInTableException.xml @@ -57,31 +57,31 @@ Represents the exception that is thrown when you try to perform an operation on a that is not in a . - is thrown when invoking the following methods on a row that has been deleted with either the or the method. - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example creates a with one and 10 objects. After deleting a row, the method is called causing the to be thrown. - + is thrown when invoking the following methods on a row that has been deleted with either the or the method. + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example creates a with one and 10 objects. After deleting a row, the method is called causing the to be thrown. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData RowNotInTableException Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/RowNotInTableException/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/RowNotInTableException/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/Rule.xml b/xml/System.Data/Rule.xml index cdeed361bfc..59dbceeb401 100644 --- a/xml/System.Data/Rule.xml +++ b/xml/System.Data/Rule.xml @@ -48,7 +48,7 @@ values are set to the and the properties of a object found in a object's . + The values are set to the and the properties of a object found in a object's . The values determine the action that occurs when a value in a column is either deleted or updated. Of the two, deleting a value is the more critical and demanding of attention when setting a rule. @@ -58,7 +58,7 @@ Constraints on a are not enforced unless the property is `true`. - When the method is called, the further determines what action occurs. + When the method is called, the further determines what action occurs. diff --git a/xml/System.Data/TypedTableBaseExtensions.xml b/xml/System.Data/TypedTableBaseExtensions.xml index f21b80b4e8c..fd9c9c3efc4 100644 --- a/xml/System.Data/TypedTableBaseExtensions.xml +++ b/xml/System.Data/TypedTableBaseExtensions.xml @@ -57,13 +57,13 @@ Contains the extension methods for the class. - method and standard query operations for typed data sets. - - This class cannot be instantiated. - + method and standard query operations for typed data sets. + + This class cannot be instantiated. + ]]> Standard Query Operators Overview (Visual Basic) @@ -546,11 +546,11 @@ Projects each element of a into a new form. An whose elements are the result of invoking the transformation function on each element of . - diff --git a/xml/System.Data/UniqueConstraint.xml b/xml/System.Data/UniqueConstraint.xml index 77d056934eb..2af7a701427 100644 --- a/xml/System.Data/UniqueConstraint.xml +++ b/xml/System.Data/UniqueConstraint.xml @@ -599,7 +599,7 @@ objects created by using this constructor must then be added to the collection via . Columns with the specified names must exist at the time the method is called, or if has been called prior to calling this constructor, the columns with the specified names must exist at the time that is called. + This constructor is provided for design time support in the Visual Studio .NET environment. objects created by using this constructor must then be added to the collection via . Columns with the specified names must exist at the time the method is called, or if has been called prior to calling this constructor, the columns with the specified names must exist at the time that is called. ]]> diff --git a/xml/System.Data/XmlReadMode.xml b/xml/System.Data/XmlReadMode.xml index c3c474c16b6..9c29f28dac1 100644 --- a/xml/System.Data/XmlReadMode.xml +++ b/xml/System.Data/XmlReadMode.xml @@ -45,20 +45,20 @@ Specifies how to read XML data and a relational schema into a . - method. - + method. + > [!NOTE] -> `Auto` mode may be slower than setting to an explicit option. +> `Auto` mode may be slower than setting to an explicit option. + +`Auto` performs the most appropriate of these actions: -`Auto` performs the most appropriate of these actions: - -- If the data is a DiffGram, sets the XML read mode to `DiffGram`. +- If the data is a DiffGram, sets the XML read mode to `DiffGram`. + +- If the dataset already has a schema, or if the document contains an in-line schema, sets the XML read mode to `ReadSchema`. -- If the dataset already has a schema, or if the document contains an in-line schema, sets the XML read mode to `ReadSchema`. - - If the dataset does not already have a schema and the document does not contain an in-line schema, sets the XML read mode to `InferSchema`. ]]> @@ -146,7 +146,7 @@ 4 Reads a DiffGram, applying changes from the DiffGram to the . The semantics are identical to those of a operation. As with the operation, values are preserved. Input to with DiffGrams should only be obtained using the output from as a DiffGram. - + The target must have the same schema as the on which as DiffGram is called. Otherwise the DiffGram merge operation fails and an exception is thrown. To be added. diff --git a/xml/System.Data/XmlWriteMode.xml b/xml/System.Data/XmlWriteMode.xml index 21a26303928..0a98e9cca2f 100644 --- a/xml/System.Data/XmlWriteMode.xml +++ b/xml/System.Data/XmlWriteMode.xml @@ -45,11 +45,11 @@ Specifies how to write XML data and a relational schema from a . - method. - + method. + ]]> diff --git a/xml/System.Device.Location/CivicAddress.xml b/xml/System.Device.Location/CivicAddress.xml index 30713449cae..91b9f301861 100644 --- a/xml/System.Device.Location/CivicAddress.xml +++ b/xml/System.Device.Location/CivicAddress.xml @@ -16,28 +16,28 @@ Represents a civic address. A civic address can include fields such as street address, postal code, state/province, and country or region. - by using a class that implements . - - The class provides a default implementation that returns the civic address that corresponds to a , if the location source provides both coordinate data as well as civic address data. - - returns a for the current location. If the location source is unable to resolve the coordinate position to a civic address, is returned. - - - -## Examples - The following example shows how to resolve a from a location synchronously. - + by using a class that implements . + + The class provides a default implementation that returns the civic address that corresponds to a , if the location source provides both coordinate data as well as civic address data. + + returns a for the current location. If the location source is unable to resolve the coordinate position to a civic address, is returned. + + + +## Examples + The following example shows how to resolve a from a location synchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: - - The following example shows how to resolve a from a location asynchronously. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: + + The following example shows how to resolve a from a location asynchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddressasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet1"::: + ]]> @@ -66,11 +66,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -264,11 +264,11 @@ Gets or sets the country or region of the location. The country or region code. If the data is not provided, returns . - @@ -324,14 +324,14 @@ if the is equal to ; otherwise, . - to check the that is returned from before the civic address is printed out. - + to check the that is returned from before the civic address is printed out. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet2"::: + ]]> @@ -416,19 +416,19 @@ Represents a that contains no data. - to verify whether a contains data. - - - -## Examples - The following example uses to check the that is returned from before the civic address is printed out. - + to verify whether a contains data. + + + +## Examples + The following example uses to check the that is returned from before the civic address is printed out. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Device.Location/CivicAddressResolver.xml b/xml/System.Device.Location/CivicAddressResolver.xml index cdc7fabbe1e..f2817f50089 100644 --- a/xml/System.Device.Location/CivicAddressResolver.xml +++ b/xml/System.Device.Location/CivicAddressResolver.xml @@ -20,24 +20,24 @@ Provides functionality for resolving a coordinate-based location to a civic address. - class provides an implementation of that resolves a coordinate-based location to a civic address if the location provider provides both coordinates and civic address data. - - - -## Examples - The following program shows how to call to resolve a civic address synchronously. - + class provides an implementation of that resolves a coordinate-based location to a civic address if the location provider provides both coordinates and civic address data. + + + +## Examples + The following program shows how to call to resolve a civic address synchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: - - The following program shows how to call to resolve a civic address asynchronously. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: + + The following program shows how to call to resolve a civic address asynchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: + ]]> @@ -57,16 +57,16 @@ Initializes a new instance of the class. - class. - -```csharp -CivicAddressResolver resolver = new CivicAddressResolver(); - -``` - + class. + +```csharp +CivicAddressResolver resolver = new CivicAddressResolver(); + +``` + ]]> @@ -97,19 +97,19 @@ CivicAddressResolver resolver = new CivicAddressResolver(); Synchronously resolves a civic address from a location based on latitude and longitude. This call will block execution of the calling thread while the address is being resolved. The civic address that is resolved from the parameter. is returned if the address cannot be resolved. - event is raised when the address resolve operation completes. The civic address that is resolved from the `coordinate` parameter is returned by the member of the object that is passed to the event handler. - - - -## Examples - The following program demonstrates how to call to resolve a civic address synchronously. - + event is raised when the address resolve operation completes. The civic address that is resolved from the `coordinate` parameter is returned by the member of the object that is passed to the event handler. + + + +## Examples + The following program demonstrates how to call to resolve a civic address synchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: + ]]> @@ -148,10 +148,10 @@ CivicAddressResolver resolver = new CivicAddressResolver(); ## Remarks This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following program shows how to call to resolve a civic address asynchronously. - + +## Examples + The following program shows how to call to resolve a civic address asynchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddressasync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet1"::: @@ -185,14 +185,14 @@ This method stores in the task it returns all non-usage exceptions that the meth Occurs when the address resolution that was initiated by a call to completes. - to resolve a civic address asynchronously. - + to resolve a civic address asynchronously. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddressasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Device.Location/GeoCoordinate.xml b/xml/System.Device.Location/GeoCoordinate.xml index 20211191c59..a6e10a8d81c 100644 --- a/xml/System.Device.Location/GeoCoordinate.xml +++ b/xml/System.Device.Location/GeoCoordinate.xml @@ -240,7 +240,7 @@ ## Examples - The following example prints the and properties of the current location's . + The following example prints the and properties of the current location's . :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Course/courseandspeed.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: @@ -290,7 +290,7 @@ objects have the same and properties. The , , and properties are not used to determine equivalency. + Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. ]]> @@ -323,7 +323,7 @@ objects have the same and properties. The , , and properties are not used to determine equivalency. + Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. ]]> @@ -386,7 +386,7 @@ objects that are equivalent have the same hash code. Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. + objects that are equivalent have the same hash code. Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. ]]> @@ -582,7 +582,7 @@ objects have the same and properties. The , , and properties are not used to determine equivalency. + Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. ]]> @@ -617,7 +617,7 @@ objects have the same and properties. The , , and properties are not used to determine equivalency. + Equivalent objects have the same and properties. The , , and properties are not used to determine equivalency. ]]> @@ -651,7 +651,7 @@ and properties of the current location's . + The following example prints the and properties of the current location's . :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Course/courseandspeed.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.courseandspeed/vb/courseandspeed.vb" id="Snippet2"::: diff --git a/xml/System.Device.Location/GeoCoordinateWatcher.xml b/xml/System.Device.Location/GeoCoordinateWatcher.xml index 4000cf472f7..bcd1837fa6c 100644 --- a/xml/System.Device.Location/GeoCoordinateWatcher.xml +++ b/xml/System.Device.Location/GeoCoordinateWatcher.xml @@ -37,11 +37,11 @@ ## Remarks The class supplies coordinate-based location data from the current location provider. The current location provider is prioritized as the highest on the computer, based on a number of factors, such as the age and accuracy of the data from all providers, the accuracy requested by location applications, and the power consumption and performance impact associated with the location provider. The current location provider might change over time, for instance, when a GPS device loses its satellite signal indoors and a Wi-Fi triangulation provider becomes the most accurate provider on the computer. - To begin accessing location data, create a and call or to initiate the acquisition of data from the current location provider. + To begin accessing location data, create a and call or to initiate the acquisition of data from the current location provider. The property can be checked to determine if data is available. If data is available, you can get the location one time from the property, or receive continuous location updates by handling the event. - The , , and properties support , so that an application can data-bind to these properties. + The , , and properties support , so that an application can data-bind to these properties. In Windows 7, all the classes are fully functional if a location provider is installed and able to resolve the computer's location. @@ -52,7 +52,7 @@ - All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -88,7 +88,7 @@ - All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -126,7 +126,7 @@ - All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -163,7 +163,7 @@ - All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -210,7 +210,7 @@ when you are finished using the class. + Call when you are finished using the class. This method should be called so that unmanaged resources can be freed. @@ -251,7 +251,7 @@ when you are finished using the class. + Call when you are finished using the class. This method should be called so that unmanaged resources can be freed. @@ -287,7 +287,7 @@ when you are finished using the class. + Call when you are finished using the class. This method should be called so that unmanaged resources can be freed. @@ -355,11 +355,11 @@ - All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. - The following diagram represents location coordinates that the location provider (for example, a GPS device) supplies to the computer. P1, in the diagram, represents the location data included in a event, and P2, P3, and P4 represent points within the movement threshold. So when the location provider supplies data indicating a location at those points (P1, P2, P3, and P4), no events are raised, and returns P1. The point P5 is outside of the distance, so at that point, is updated and a event is raised. + The following diagram represents location coordinates that the location provider (for example, a GPS device) supplies to the computer. P1, in the diagram, represents the location data included in a event, and P2, P3, and P4 represent points within the movement threshold. So when the location provider supplies data indicating a location at those points (P1, P2, P3, and P4), no events are raised, and returns P1. The point P5 is outside of the distance, so at that point, is updated and a event is raised. ![Diagram illustrating MovementThreshold](~/add/media/ndp-movementthreshold.png "Diagram illustrating MovementThreshold") @@ -512,7 +512,7 @@ property of the property is saved in a object. The latitude and longitude fields of the are printed if they are known. + In the following example, the property of the property is saved in a object. The latitude and longitude fields of the are printed if they are known. :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdatasync.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet2"::: @@ -546,9 +546,9 @@ . + This event is only raised when the distance moved since the last event exceeds the threshold that is specified by . - The object passed to the event handler includes the object that contains the updated location data. + The object passed to the event handler includes the object that contains the updated location data. @@ -605,9 +605,9 @@ ## Remarks Calling this method will initiate the acquisition of data from the current location provider. The current location provider is selected based on factors such as the age and accuracy of the data from all providers, the accuracy requested by the application or applications, and the power consumption and performance impact associated with the location provider. The current location provider might change over time, for instance, when a GPS device loses its satellite signal indoors and a Wi-Fi triangulation provider becomes the most accurate provider on the computer. - If the current prioritized location provider does not have data when the method is called, it will start to acquire data. If the permissions have been granted to the client when the data becomes available, data can be accessed synchronously, and will be delivered asynchronously if events are being handled. + If the current prioritized location provider does not have data when the method is called, it will start to acquire data. If the permissions have been granted to the client when the data becomes available, data can be accessed synchronously, and will be delivered asynchronously if events are being handled. - If the Windows 7 Sensor and Location platform is disabled when is called, will immediately return, events will not be raised, and the location returned by the property of will contain . + If the Windows 7 Sensor and Location platform is disabled when is called, will immediately return, events will not be raised, and the location returned by the property of will contain . If the current prioritized location provider does have data, it will be available synchronously immediately, and will be delivered asynchronously if events are being handled. @@ -616,7 +616,7 @@ ## Examples - The following program handles the first location update that occurs after is called. + The following program handles the first location update that occurs after is called. :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Start/getlocationdataupdateonce.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataupdateonce/vb/GetLocationDataUpdateOnce.vb" id="Snippet1"::: @@ -690,7 +690,7 @@ events and prints a message based on the . + The following example handles events and prints a message based on the . :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Status/showstatusupdates.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.showstatusupdates/vb/ShowStatusUpdates.vb" id="Snippet1"::: @@ -770,9 +770,9 @@ is called, no further events occur, and the property will return . + After is called, no further events occur, and the property will return . - When is called, the property is set to . + When is called, the property is set to . ]]> @@ -921,12 +921,12 @@ This member is an explicit interface member implementation. It can be used only from the user interface thread of your application. + This method blocks execution of the calling thread during the time period specified by `timeout`. Use caution when calling from the user interface thread of your application. ## Examples - The following example demonstrates how to call . + The following example demonstrates how to call . :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdatasync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet1"::: diff --git a/xml/System.Device.Location/GeoPositionStatusChangedEventArgs.xml b/xml/System.Device.Location/GeoPositionStatusChangedEventArgs.xml index 009439ad656..e2f9080195f 100644 --- a/xml/System.Device.Location/GeoPositionStatusChangedEventArgs.xml +++ b/xml/System.Device.Location/GeoPositionStatusChangedEventArgs.xml @@ -37,11 +37,11 @@ The new status. Initializes a new instance of the GeoPositionStatusChangedEventArgs class. - . - + . + ]]> diff --git a/xml/System.Device.Location/ICivicAddressResolver.xml b/xml/System.Device.Location/ICivicAddressResolver.xml index f7c215ef1cb..4a8fa3dcdb4 100644 --- a/xml/System.Device.Location/ICivicAddressResolver.xml +++ b/xml/System.Device.Location/ICivicAddressResolver.xml @@ -13,11 +13,11 @@ Provides a method that when implemented, resolves a latitude/longitude location to a civic address. - to a asynchronously, implement , and provide the civic address data to the event. - + to a asynchronously, implement , and provide the civic address data to the event. + ]]> @@ -46,14 +46,14 @@ Resolves a to a civic address synchronously. To be added. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddresssync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddresssync/vb/resolvecivicaddresssync.vb" id="Snippet1"::: + ]]> @@ -85,10 +85,10 @@ ## Remarks This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example shows how to call . - + +## Examples + The following example shows how to call . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddressasync.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet2"::: @@ -115,14 +115,14 @@ This method stores in the task it returns all non-usage exceptions that the meth Occurs when an asynchronous request using to resolve a latitude/longitude to a civic address is complete. - and handle the event. - + and handle the event. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/CivicAddress/Overview/resolvecivicaddressasync.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.resolvecivicaddressasync/vb/resolvecivicaddressasync.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Device.Location/IGeoPositionWatcher`1.xml b/xml/System.Device.Location/IGeoPositionWatcher`1.xml index 4b2cd46b2e2..272616fc2cc 100644 --- a/xml/System.Device.Location/IGeoPositionWatcher`1.xml +++ b/xml/System.Device.Location/IGeoPositionWatcher`1.xml @@ -17,11 +17,11 @@ The type of the object that contains the location data. Interface that can be implemented for providing accessing location data and receiving location updates. - class implements , using as the type parameter. - + class implements , using as the type parameter. + ]]> @@ -119,8 +119,8 @@ - If , do not prompt the user to enable location providers and only start if location data is already enabled. - + If , do not prompt the user to enable location providers and only start if location data is already enabled. + If , a dialog box may be displayed to prompt the user to enable location sensors that are disabled. Start acquiring location data, specifying whether or not to suppress prompting for permissions. This method returns synchronously. To be added. @@ -210,8 +210,8 @@ - If , do not prompt the user to enable location providers and only start if location data is already enabled. - + If , do not prompt the user to enable location providers and only start if location data is already enabled. + If , a dialog box may be displayed to prompt the user to enable location sensors that are disabled. Time in milliseconds to wait for initialization to complete. Start acquiring location data, specifying an initialization timeout. This method returns synchronously. diff --git a/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml index edfaff4b480..3c7e966ee24 100644 --- a/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml @@ -274,7 +274,7 @@ The pro ## Remarks -Concatenated together, the and properties form a unique check identifier. +Concatenated together, the and properties form a unique check identifier. ## Examples The following code example shows the use of the attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics.Contracts.Internal/ContractHelper.xml b/xml/System.Diagnostics.Contracts.Internal/ContractHelper.xml index 5f2711840f5..7f89a494547 100644 --- a/xml/System.Diagnostics.Contracts.Internal/ContractHelper.xml +++ b/xml/System.Diagnostics.Contracts.Internal/ContractHelper.xml @@ -68,11 +68,11 @@ Used by the binary rewriter to activate the default failure behavior. A null reference ( in Visual Basic) if the event was handled and should not trigger a failure; otherwise, returns the localized failure message. - method does not perform the failure behavior (an assert or throw) itself. If the failure is handled by the listeners, the method returns `null`. If the failure is not handled by the listeners, a localized failure message is returned. - + method does not perform the failure behavior (an assert or throw) itself. If the failure is handled by the listeners, the method returns `null`. If the failure is not handled by the listeners, a localized failure message is returned. + ]]> @@ -123,11 +123,11 @@ The inner exception that caused the current exception. Triggers the default failure behavior. - , which causes the **Assert** dialog box to be displayed. You can change that behavior to throw an instead of displaying the dialog box. - + , which causes the **Assert** dialog box to be displayed. You can change that behavior to throw an instead of displaying the dialog box. + ]]> diff --git a/xml/System.Diagnostics.Contracts/Contract.xml b/xml/System.Diagnostics.Contracts/Contract.xml index 3efbff29c6a..59d9205dcdd 100644 --- a/xml/System.Diagnostics.Contracts/Contract.xml +++ b/xml/System.Diagnostics.Contracts/Contract.xml @@ -59,7 +59,7 @@ For tools and detailed instructions for using code contracts, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. > [!IMPORTANT] -> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with Visual Studio 2010 or the Windows SDK. +> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with Visual Studio 2010 or the Windows SDK. ]]> @@ -295,7 +295,7 @@ method. + At run time, using this method is equivalent to using the method. ]]> @@ -371,7 +371,7 @@ ## Remarks If `userMessage` is not a constant string literal, the contract may not be understood by tools. - At run time, using this method is equivalent to using the method. + At run time, using this method is equivalent to using the method. ]]> @@ -434,7 +434,7 @@ ## Remarks The event information for this event is supplied by the object that is passed to the event handler. This event notifies a managed application environment such as an interactive interpreter or a Web browser host that a contract has failed. Before doing so, it will raise an event that an application can handle as it sees fit. For example, if code is being run in a testing framework, you can log a test failure and then end the test. - The default implementation of the method in the .NET Framework class library is to call each handler that is registered with the event. Exceptions thrown by handlers are ignored, but each handler can indicate whether the failure is handled by calling the method for the event arguments. If any handler sets the failure as handled, the method returns `null` and no further action is taken. Alternatively, handlers can call the method to instruct the code to unwind. In that case, an exception is thrown after all handlers have executed. + The default implementation of the method in the .NET Framework class library is to call each handler that is registered with the event. Exceptions thrown by handlers are ignored, but each handler can indicate whether the failure is handled by calling the method for the event arguments. If any handler sets the failure as handled, the method returns `null` and no further action is taken. Alternatively, handlers can call the method to instruct the code to unwind. In that case, an exception is thrown after all handlers have executed. ]]> @@ -491,9 +491,9 @@ method call, such as a , , , or . + Most code already contains some parameter validation in the form of `if`-`then`-`throw` code. The contract tools recognize `if`-`then`-`throw` statements as preconditions when the statements appear first inside a method, and the entire set of such statements is followed by an explicit method call, such as a , , , or . - When `if`-`then`-`throw` statements appear in this form, the contract tools recognize them as legacy-require statements. The form is used only if no other contracts follow the `if`-`then`-`throw` sequences, but they should still be tagged as legacy-requires. + When `if`-`then`-`throw` statements appear in this form, the contract tools recognize them as legacy-require statements. The form is used only if no other contracts follow the `if`-`then`-`throw` sequences, but they should still be tagged as legacy-requires. ]]> @@ -572,7 +572,7 @@ ## Examples - The following example shows how to use the method to ensure that an expected value is returned. This code example is part of a larger example provided for the class. + The following example shows how to use the method to ensure that an expected value is returned. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet3"::: @@ -1018,7 +1018,7 @@ ## Examples - The following example demonstrates how to use the method to determine whether an array has a null element. + The following example demonstrates how to use the method to determine whether an array has a null element. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/ForAll/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/ForAll/program.vb" id="Snippet1"::: @@ -1098,7 +1098,7 @@ method to determine whether a collection has a null element. + The following example demonstrates how to use the method to determine whether a collection has a null element. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/ForAll/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/ForAll/program.vb" id="Snippet1"::: @@ -1175,7 +1175,7 @@ contracts are contained within a method that is identified by the attribute; typically, the method is named `ObjectInvariant`. + contracts are contained within a method that is identified by the attribute; typically, the method is named `ObjectInvariant`. - This contract can be specified only in a dedicated invariant method that is declared on a class. If the method is not sealed, it should refer only to protected members, not private members, so that subclasses can be sure to maintain the invariants. @@ -1246,7 +1246,7 @@ contracts are contained within a method that is identified by the attribute; typically, the method is named `ObjectInvariant`. + contracts are contained within a method that is identified by the attribute; typically, the method is named `ObjectInvariant`. - This contract can be specified only in a dedicated invariant method that is declared on a class. @@ -1322,12 +1322,12 @@ contract. + This method can be used only in the conditional expression for the contract. ## Examples - The following example shows the use of the method to ensure that a count has been updated. This code example is part of a larger example provided for the class. + The following example shows the use of the method to ensure that a count has been updated. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet5"::: @@ -1405,7 +1405,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. +- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. ]]> @@ -1473,7 +1473,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. +- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. ]]> @@ -1539,13 +1539,13 @@ ## Remarks > [!IMPORTANT] -> You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. +> You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. - This method call must be at the beginning of a method or property, before any other code. - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when you want to throw an exception if the precondition fails. +- Use this method instead of the method when you want to throw an exception if the precondition fails. ]]> @@ -1621,13 +1621,13 @@ ## Remarks - > [!IMPORTANT] - > You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. + > You must turn on run-time checking to use the method. If run-time checking is turned off, the process will be terminated. To obtain the tools for runtime checking, see [Code Contracts](https://marketplace.visualstudio.com/items?itemName=RiSEResearchinSoftwareEngineering.CodeContractsforNET) on the Visual Studio Marketplace. This method call must be at the beginning of a method or property, before any other code. - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when you want to throw an exception if the precondition fails. +- Use this method instead of the method when you want to throw an exception if the precondition fails. ]]> @@ -1692,12 +1692,12 @@ contract. + This method can be used only in the conditional expression for the contract. ## Examples - The following example shows how to use the method to specify an expected return value. This code example is part of a larger example provided for the class. + The following example shows how to use the method to specify an expected return value. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet3"::: @@ -1768,7 +1768,7 @@ contract. As with the method, you can omit the generic type parameter whenever the compiler is able to infer its type. The contract rewriter replaces the method call with the value of the `out` parameter. The method may appear only in postconditions. The argument to the method must be an `out` parameter or a field of a structure `out` parameter. The latter is also useful when referring to fields in the postcondition of a structure constructor. + This method can be used only in the conditional expression for the contract. As with the method, you can omit the generic type parameter whenever the compiler is able to infer its type. The contract rewriter replaces the method call with the value of the `out` parameter. The method may appear only in postconditions. The argument to the method must be an `out` parameter or a field of a structure `out` parameter. The latter is also useful when referring to fields in the postcondition of a structure constructor. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml b/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml index 28efa19cd07..750813caeab 100644 --- a/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml @@ -55,37 +55,37 @@ Enables the factoring of legacy code into separate methods for reuse, and provides full control over thrown exceptions and arguments. - attribute. The method call should be used to enable the tools to extract the proper specifications for document generation and static checking, as follows. - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow1.vb" id="Snippet1"::: + + In this example, `Execute` has an elective precondition specifying that the parameter value should not be `null`. To enable the contract tools to recognize that the call to `ValidationHelper.NotNull` represents a contract, you can mark the called method with the attribute. The method call should be used to enable the tools to extract the proper specifications for document generation and static checking, as follows. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow2.vb" id="Snippet2"::: - - In addition to `if-then-throw` statements, the contract section of contract validator methods may contain calls to other contract validator methods. However, no other contracts (such as , or ) are allowed. Code that follows the call is ignored by all contract tools. - - The following example shows a range argument validator written in terms of an existing `NotNull` validator method. - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow2.vb" id="Snippet2"::: + + In addition to `if-then-throw` statements, the contract section of contract validator methods may contain calls to other contract validator methods. However, no other contracts (such as , or ) are allowed. Code that follows the call is ignored by all contract tools. + + The following example shows a range argument validator written in terms of an existing `NotNull` validator method. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow3.vb" id="Snippet3"::: - - From a specification point of view, the `Execute` method has the following three contracts: - -``` -Contract.Requires(data != null); -Contract.Requires(position >= 0); -Contract.Requires(position < data.Length); - -``` - - In standard methods, calls to contract validator methods can be freely mixed with other contracts such as or . - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow3.vb" id="Snippet3"::: + + From a specification point of view, the `Execute` method has the following three contracts: + +``` +Contract.Requires(data != null); +Contract.Requires(position >= 0); +Contract.Requires(position < data.Length); + +``` + + In standard methods, calls to contract validator methods can be freely mixed with other contracts such as or . + ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractClassAttribute.xml b/xml/System.Diagnostics.Contracts/ContractClassAttribute.xml index 90b61588933..af725cb1e05 100644 --- a/xml/System.Diagnostics.Contracts/ContractClassAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractClassAttribute.xml @@ -63,19 +63,19 @@ Specifies that a separate type contains the code contracts for this type. - attribute to specify that the contracts for the `IArray` interface are contained in the `IArrayContracts` class. - + attribute to specify that the contracts for the `IArray` interface are contained in the `IArrayContracts` class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet1"::: + ]]> @@ -119,14 +119,14 @@ The type that contains the code contracts for this type. Initializes a new instance of the class. - constructor to specify that the contracts for the `IArray` interface are contained in the `IArrayContracts` class. - + constructor to specify that the contracts for the `IArray` interface are contained in the `IArrayContracts` class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Contracts/Contract/Ensures/program.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractClassForAttribute.xml b/xml/System.Diagnostics.Contracts/ContractClassForAttribute.xml index 16f11cdfb98..94c4228090b 100644 --- a/xml/System.Diagnostics.Contracts/ContractClassForAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractClassForAttribute.xml @@ -59,18 +59,18 @@ Specifies that a class is a contract for a type. - attribute to specify the contracts for another type. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet4"::: - + attribute to specify the contracts for another type. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet4"::: + ]]> @@ -114,13 +114,13 @@ The type the current class is a contract for. Initializes a new instance of the class, specifying the type the current class is a contract for. - constructor to specify that the contracts in the type apply to the `IArray` interface. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet4"::: - + constructor to specify that the contracts in the type apply to the `IArray` interface. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/Contract/Ensures/program.cs" id="Snippet4"::: + ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml index 65eadc167d5..0695e7c1889 100644 --- a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml +++ b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml @@ -371,7 +371,7 @@ method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. + The method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. ]]> @@ -424,7 +424,7 @@ method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. + The method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml b/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml index ca4bd870f0d..7af30f599ef 100644 --- a/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml @@ -55,11 +55,11 @@ Marks a method as being the invariant method for a class. - method. A type can have more than one contract invariant method, which can be public or private. - + method. A type can have more than one contract invariant method, which can be public or private. + ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractOptionAttribute.xml b/xml/System.Diagnostics.Contracts/ContractOptionAttribute.xml index 3a927dc8c5f..a2acb1ee05b 100644 --- a/xml/System.Diagnostics.Contracts/ContractOptionAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractOptionAttribute.xml @@ -215,7 +215,7 @@ public override MyMethod(int x) { overload by specifying "true" or "false" in string format; for example: + There are only two category/setting options, and they can be set by either of the constructor overloads. You can use this overload with the same settings as the overload by specifying "true" or "false" in string format; for example: ```csharp [ContractOption("contract", "inheritance", "false")] diff --git a/xml/System.Diagnostics.Eventing.Reader/EventLogConfiguration.xml b/xml/System.Diagnostics.Eventing.Reader/EventLogConfiguration.xml index 24213ae1558..8c9b03c5ed8 100644 --- a/xml/System.Diagnostics.Eventing.Reader/EventLogConfiguration.xml +++ b/xml/System.Diagnostics.Eventing.Reader/EventLogConfiguration.xml @@ -39,7 +39,7 @@ method to save the changes. + If a property is changed for this object, call the method to save the changes. @@ -326,7 +326,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -369,7 +369,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -448,7 +448,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -569,7 +569,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -720,7 +720,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -799,7 +799,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> @@ -986,7 +986,7 @@ method to save the changes. + If the value of this property is changed, call the method to save the changes. ]]> diff --git a/xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml b/xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml index 70061a55fa1..65251967e7a 100644 --- a/xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml +++ b/xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml @@ -99,7 +99,7 @@ method to retrieve events from this object. + Use the method to retrieve events from this object. ]]> @@ -142,7 +142,7 @@ method to retrieve events from this object. + Use the method to retrieve events from this object. ]]> @@ -193,7 +193,7 @@ method to retrieve events from this object. + Use the method to retrieve events from this object. ]]> @@ -238,7 +238,7 @@ method to retrieve events from this object. + Use the method to retrieve events from this object. ]]> diff --git a/xml/System.Diagnostics.Eventing/EventDescriptor.xml b/xml/System.Diagnostics.Eventing/EventDescriptor.xml index 17124425a19..fd7e30bc6fb 100644 --- a/xml/System.Diagnostics.Eventing/EventDescriptor.xml +++ b/xml/System.Diagnostics.Eventing/EventDescriptor.xml @@ -17,26 +17,26 @@ Contains the metadata that defines an event. - or method. - + or method. + ]]> @@ -73,11 +73,11 @@ unchecked Bit mask that specifies the event category. The keyword can contain one or more provider-defined keywords, standard keywords, or both. Initializes a new instance of the class. - @@ -276,11 +276,11 @@ unchecked Retrieves the version value from the event descriptor. The version of the event. - diff --git a/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml b/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml index c57f842c659..2afeb7581f9 100644 --- a/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml +++ b/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml @@ -16,13 +16,13 @@ Defines the possible states of the last write operation. - method. - - The , , and methods set this value if they fail to write the event. - + method. + + The , , and methods set this value if they fail to write the event. + ]]> diff --git a/xml/System.Diagnostics.Eventing/EventProvider.xml b/xml/System.Diagnostics.Eventing/EventProvider.xml index 7016019ab80..74074d4eeb1 100644 --- a/xml/System.Diagnostics.Eventing/EventProvider.xml +++ b/xml/System.Diagnostics.Eventing/EventProvider.xml @@ -24,7 +24,7 @@ and methods, the events must be defined in a manifest; events written using the method do not require a manifest. + To consume events written using the and methods, the events must be defined in a manifest; events written using the method do not require a manifest. Events can contain the following managed data types: @@ -99,7 +99,7 @@ method. + Registers the provider. To remove the registration when finished, call the method. ]]> @@ -291,7 +291,7 @@ , , and methods set this value if they fail to write the event. + The , , and methods set this value if they fail to write the event. This is a static method. @@ -407,7 +407,7 @@ ## Remarks The identifier is stored in the thread context. - Note that in version 3.5 of the .NET framework, you had to set the `id` parameter of this method and the property value to the same identifier value. However, in version 4.0 of the framework, the method automatically sets the correlation activity identifier for you. + Note that in version 3.5 of the .NET framework, you had to set the `id` parameter of this method and the property value to the same identifier value. However, in version 4.0 of the framework, the method automatically sets the correlation activity identifier for you. This is a static method. @@ -476,9 +476,9 @@ method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. + If you call the method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. - If the object type is not supported, the method writes the value of the object's method in the payload. For a list of supported object types, see the Remarks for the class. + If the object type is not supported, the method writes the value of the object's method in the payload. For a list of supported object types, see the Remarks for the class. @@ -563,7 +563,7 @@ enum Level method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. + If you call the method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. The maximum string length is limited to 64 KB minus the size of the event headers. The event size is less if the session's buffer size is less and the session includes extended data items with the event. @@ -633,7 +633,7 @@ provider.Close(); method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. + If you call the method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. ]]> @@ -812,9 +812,9 @@ if (!provider.WriteMessageEvent("Event string.", 3, 2)) method. + The method uses the activity ID set in the thread context to identify this component. To set the activity ID, call the method. - If you use the class, you do not use the method to specify the activity ID. Instead, access the property to get the object. Then, set the property to the activity ID. You must also set the `relatedActivityId` to a value. + If you use the class, you do not use the method to specify the activity ID. Instead, access the property to get the object. Then, set the property to the activity ID. You must also set the `relatedActivityId` to a value. ]]> @@ -860,7 +860,7 @@ if (!provider.WriteMessageEvent("Event string.", 3, 2)) method. + The method uses the activity ID set in the thread context to identify this component. To set the activity ID, call the method. ]]> diff --git a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml index 3677494a556..0295305da61 100644 --- a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml +++ b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml @@ -212,7 +212,7 @@ private static Guid providerId = new Guid("{B3F0C8FC-E8A8-4868-8901-1465E8A2F41B You do not need a manifest to consume events from the listener because the event data is a single string. - The delimiter applies to event data written using the method. + The delimiter applies to event data written using the method. ]]> diff --git a/xml/System.Diagnostics.PerformanceData/CounterData.xml b/xml/System.Diagnostics.PerformanceData/CounterData.xml index 27e8030bf07..05838298dd0 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterData.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterData.xml @@ -85,7 +85,7 @@ ## Remarks This method safely decrements the counter value for multi-threaded applications. - To decrement the counter value by a specific value, call the method and set the `value` parameter to a negative number. + To decrement the counter value by a specific value, call the method and set the `value` parameter to a negative number. To set the counter value, use the property. @@ -137,7 +137,7 @@ To set the counter value, use the property. - To increment the counter value by a specific value, call the method. + To increment the counter value by a specific value, call the method. ]]> @@ -190,7 +190,7 @@ To set the counter value, use the property. - To increment the counter value by 1, call the method. + To increment the counter value by 1, call the method. ]]> @@ -295,7 +295,7 @@ Note that the property is not thread safe in .NET Framework 3.5. - To increment the counter value, consider using the or method. + To increment the counter value, consider using the or method. diff --git a/xml/System.Diagnostics.PerformanceData/CounterSet.xml b/xml/System.Diagnostics.PerformanceData/CounterSet.xml index 66c6de24272..6d313fdc899 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSet.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSet.xml @@ -36,16 +36,16 @@ Defines a set of logical counters. - method when you are finished to remove your provider's registration and to release all managed and unmanaged resources. - - - -## Examples - For an example, see . - + method when you are finished to remove your provider's registration and to release all managed and unmanaged resources. + + + +## Examples + For an example, see . + ]]> @@ -96,16 +96,16 @@ Identifies the type of the counter set, for example, whether the counter set is a single or multiple instance counter set. Initializes a new instance of the class. - method removes the registration. - - - -## Examples - For an example, see . - + method removes the registration. + + + +## Examples + For an example, see . + ]]> Not enough memory is available to complete the operation. @@ -160,11 +160,11 @@ Identifies the counter type. The counter type determines how the counter data is calculated, averaged, and displayed. Adds a counter to the counter set by using the specified counter identifier and type. - The counter identifier already exists in the set or is negative, or the counter type is NULL or not valid. @@ -210,16 +210,16 @@ Name of the counter. You can use this name to index the counter in the counter set instance. (See .) Adds a counter to the counter set by using the specified counter identifier and type and a display name for the counter. - . - + . + ]]> The counter identifier already exists in the set or is negative, or the counter type is NULL or not valid. @@ -272,20 +272,20 @@ Creates an instance of the counter set. An instance of the counter set which will contain the counter data. - . - + . + ]]> The instance name is NULL. @@ -422,11 +422,11 @@ Frees resources before the object is reclaimed by garbage collection. - diff --git a/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml b/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml index b2c2bf4a6db..5fdcb7f537a 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml @@ -36,16 +36,16 @@ Creates an instance of the logical counters defined in the class. - method returns an instance of this class. - - - -## Examples - For an example, see . - + method returns an instance of this class. + + + +## Examples + For an example, see . + ]]> @@ -88,16 +88,16 @@ Retrieves the collection of counter data for the counter set instance. A collection of the counter data contained in the counter set instance. - . - + . + ]]> diff --git a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml index ecb1e7b2781..eb411940782 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml @@ -223,7 +223,7 @@ ## Remarks Implemented as an indexer in C#. - To use this overload, you must use the method to add the counter to the counter set. + To use this overload, you must use the method to add the counter to the counter set. ]]> diff --git a/xml/System.Diagnostics.SymbolStore/ISymbolBinder.xml b/xml/System.Diagnostics.SymbolStore/ISymbolBinder.xml index 5990f60af26..303e1295b6f 100644 --- a/xml/System.Diagnostics.SymbolStore/ISymbolBinder.xml +++ b/xml/System.Diagnostics.SymbolStore/ISymbolBinder.xml @@ -50,13 +50,13 @@ Represents a symbol binder for managed code. - [!NOTE] -> This interface is the managed counterpart of the `ISymUnmanagedBinder` interface, which is one of the unmanaged symbol store interfaces that provide an alternate way to read and write debug symbol information. - +> This interface is the managed counterpart of the `ISymUnmanagedBinder` interface, which is one of the unmanaged symbol store interfaces that provide an alternate way to read and write debug symbol information. + ]]> @@ -130,11 +130,11 @@ Gets the interface of the symbol reader for the current file. The interface that reads the debugging symbols. - method returns the interface that reads the debugging symbols associated with the module. - + method returns the interface that reads the debugging symbols associated with the module. + ]]> diff --git a/xml/System.Diagnostics.SymbolStore/ISymbolBinder1.xml b/xml/System.Diagnostics.SymbolStore/ISymbolBinder1.xml index baeb1338591..d1f4449501c 100644 --- a/xml/System.Diagnostics.SymbolStore/ISymbolBinder1.xml +++ b/xml/System.Diagnostics.SymbolStore/ISymbolBinder1.xml @@ -49,13 +49,13 @@ Represents a symbol binder for managed code. - is the managed counterpart of the unmanaged `ISymUnmanagedBinder` - - interface, one of the unmanaged symbol store interfaces that provide an alternative way to read and write debug symbol information. - + is the managed counterpart of the unmanaged `ISymUnmanagedBinder` + + interface, one of the unmanaged symbol store interfaces that provide an alternative way to read and write debug symbol information. + ]]> @@ -114,11 +114,11 @@ Gets the interface of the symbol reader for the current file. The interface that reads the debugging symbols. - method returns the interface that reads the debugging symbols associated with the module. - + method returns the interface that reads the debugging symbols associated with the module. + ]]> diff --git a/xml/System.Diagnostics.SymbolStore/ISymbolDocumentWriter.xml b/xml/System.Diagnostics.SymbolStore/ISymbolDocumentWriter.xml index 2583dc6dceb..c4db348fd17 100644 --- a/xml/System.Diagnostics.SymbolStore/ISymbolDocumentWriter.xml +++ b/xml/System.Diagnostics.SymbolStore/ISymbolDocumentWriter.xml @@ -61,8 +61,8 @@ ## Examples - The following code example demonstrates how an can be obtained when calling . - + The following code example demonstrates how an can be obtained when calling . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics.SymbolStore/ISymbolMethod.xml b/xml/System.Diagnostics.SymbolStore/ISymbolMethod.xml index 5d899fea939..bfe40f830ef 100644 --- a/xml/System.Diagnostics.SymbolStore/ISymbolMethod.xml +++ b/xml/System.Diagnostics.SymbolStore/ISymbolMethod.xml @@ -50,14 +50,14 @@ Represents a method within a symbol store. - interface provides access only to the symbol-related attributes of a method, such as sequence points, lexical scopes, and parameter information. Use it with the classes to read the type-related attributes of a method. - + interface provides access only to the symbol-related attributes of a method, such as sequence points, lexical scopes, and parameter information. Use it with the classes to read the type-related attributes of a method. + > [!NOTE] -> This interface is the managed counterpart of the `ISymUnmanagedMethod` interface, one of the unmanaged symbol store interfaces that provide an alternative way to read and write debug symbol information. - +> This interface is the managed counterpart of the `ISymUnmanagedMethod` interface, one of the unmanaged symbol store interfaces that provide an alternative way to read and write debug symbol information. + ]]> @@ -155,11 +155,11 @@ Gets the Microsoft intermediate language (MSIL) offset within the method that corresponds to the specified position. The offset within the specified document. - @@ -205,11 +205,11 @@ Gets the parameters for the current method. The array of parameters for the current method. - @@ -262,11 +262,11 @@ Gets an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) that a given position covers within this method. An array of start and end offset pairs. - @@ -315,11 +315,11 @@ Returns the most enclosing lexical scope when given an offset within a method. The most enclosing lexical scope for the given byte offset within the method. - method to start local variable searches. - + method to start local variable searches. + ]]> @@ -385,13 +385,13 @@ The array of columns in the documents at which the sequence points end. Gets the sequence points for the current method. - to retrieve the count of all sequence points and create arrays of the proper size. - - verifies the size of each array and places the sequence point information into each. If any array is `null`, the data for that array is not returned. - + to retrieve the count of all sequence points and create arrays of the proper size. + + verifies the size of each array and places the sequence point information into each. If any array is `null`, the data for that array is not returned. + ]]> @@ -453,11 +453,11 @@ if the positions were defined; otherwise, . - diff --git a/xml/System.Diagnostics.SymbolStore/ISymbolWriter.xml b/xml/System.Diagnostics.SymbolStore/ISymbolWriter.xml index 92357d5ca2d..b1e81f922a9 100644 --- a/xml/System.Diagnostics.SymbolStore/ISymbolWriter.xml +++ b/xml/System.Diagnostics.SymbolStore/ISymbolWriter.xml @@ -50,14 +50,14 @@ Represents a symbol writer for managed code. - interface provides methods that define documents, sequence points, lexical scopes, and variables. - + interface provides methods that define documents, sequence points, lexical scopes, and variables. + > [!NOTE] -> This interface is the managed counterpart of the `ISymUnmanagedWriter` interface, which is one of the unmanaged symbol store interfaces that provides an alternative way to read and write debug symbol information. - +> This interface is the managed counterpart of the `ISymUnmanagedWriter` interface, which is one of the unmanaged symbol store interfaces that provides an alternative way to read and write debug symbol information. + ]]> @@ -103,11 +103,11 @@ Closes and commits the symbols to the symbol store. - becomes invalid for further updates. - + becomes invalid for further updates. + ]]> @@ -152,11 +152,11 @@ Closes the current method. - @@ -246,11 +246,11 @@ The points past the last instruction in the scope. Closes the current lexical scope. - @@ -364,11 +364,11 @@ The third address for the field specification. Defines a field in a type or a global field. - method defines a single variable that is not within a method by using specified fields in classes, bit fields, and so on. - + method defines a single variable that is not within a method by using specified fields in classes, bit fields, and so on. + ]]> @@ -489,13 +489,13 @@ The end offset for the variable. If this parameter is zero, it is ignored and the variable is defined throughout the entire scope. If the parameter is nonzero, the variable falls within the offsets of the current scope. Defines a single variable in the current lexical scope. - multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) - + multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) + ]]> @@ -555,11 +555,11 @@ The third address for the parameter specification. Defines a single parameter in the current method. The type of each parameter is taken from its position within the signature of the method. - @@ -617,11 +617,11 @@ The document end positions for the sequence points. Defines a group of sequence points within the current method. - @@ -674,11 +674,11 @@ indicates that this is a full rebuild; indicates that this is an incremental compilation. Sets the metadata emitter interface to associate with a writer. - also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods. - + also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods. + ]]> @@ -726,11 +726,11 @@ The metadata token for the method to be opened. Opens a method to place symbol information into. - @@ -778,11 +778,11 @@ The name of the new namespace. Opens a new namespace. - @@ -831,13 +831,13 @@ Opens a new lexical scope in the current method. An opaque scope identifier that can be used with to define the start and end offsets of a scope at a later time. In this case, the offsets passed to and are ignored. A scope identifier is valid only in the current method. - @@ -993,11 +993,11 @@ The attribute value. Defines an attribute when given the attribute name and the attribute value. - method is only associated with symbolic information and is not a metadata custom attribute. - + method is only associated with symbolic information and is not a metadata custom attribute. + ]]> @@ -1045,11 +1045,11 @@ A pointer to code that represents the underlying writer. Sets the underlying (the corresponding unmanaged interface) that a managed uses to emit symbols. - @@ -1097,11 +1097,11 @@ The metadata token for the method that is the user entry point. Identifies the user-defined method as the entry point for the current module. - @@ -1149,11 +1149,11 @@ The fully qualified name of the namespace. Specifies that the given, fully qualified namespace name is used within the open lexical scope. - diff --git a/xml/System.Diagnostics.SymbolStore/SymBinder.xml b/xml/System.Diagnostics.SymbolStore/SymBinder.xml index 74fb48dc38b..5eb34c71c92 100644 --- a/xml/System.Diagnostics.SymbolStore/SymBinder.xml +++ b/xml/System.Diagnostics.SymbolStore/SymBinder.xml @@ -88,7 +88,7 @@ method to release resources. ]]> @@ -116,12 +116,12 @@ Use the method to relea Releases the resources held by the current instance. - method to release resources. - + ]]> @@ -189,11 +189,11 @@ Use the method to relea to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -220,11 +220,11 @@ Use the method to relea Releases the resources held by the current instance. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -280,14 +280,14 @@ Use the method to relea Gets the interface of the symbol reader for the current file, using the specified 32-bit integer pointer to a metadata interface, the specified file name, and the specified search path. The interface that reads the debugging symbols. - method returns the interface that reads the debugging symbols associated with the module. - + method returns the interface that reads the debugging symbols associated with the module. + > [!NOTE] -> Using a 32-bit integer as a pointer is not recommended. Use the overload instead. - +> Using a 32-bit integer as a pointer is not recommended. Use the overload instead. + ]]> @@ -327,11 +327,11 @@ Use the method to relea Gets the interface of the symbol reader for the current file, using the specified pointer to a metadata interface, the specified file name, and the specified search path. The interface that reads the debugging symbols. - method returns the interface that reads the debugging symbols associated with the module. - + method returns the interface that reads the debugging symbols associated with the module. + ]]> diff --git a/xml/System.Diagnostics.SymbolStore/SymDocument.xml b/xml/System.Diagnostics.SymbolStore/SymDocument.xml index ff36c1adb97..c96e2799da6 100644 --- a/xml/System.Diagnostics.SymbolStore/SymDocument.xml +++ b/xml/System.Diagnostics.SymbolStore/SymDocument.xml @@ -38,13 +38,13 @@ Represents a document referenced by a symbol store. - @@ -69,8 +69,8 @@ method, instead of being created directly from an unmanaged interface using this constructor. +## Remarks +Typically, instances of this type are obtained by calling the method, instead of being created directly from an unmanaged interface using this constructor. ]]> @@ -119,7 +119,7 @@ Typically, instances of this type are obtained by calling the method to release resources. ]]> @@ -147,12 +147,12 @@ Use the method to rel Releases the resources held by the current instance. - method to release resources. - + ]]> @@ -249,11 +249,11 @@ Use the method to rel to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -308,11 +308,11 @@ Use the method to rel Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -516,11 +516,11 @@ The unmanaged [ISymUnmanagedDocument](/dotnet/framework/unmanaged-api/diagnostic Gets the language of the current document. A representing the language of the current document. - @@ -551,11 +551,11 @@ The unmanaged [ISymUnmanagedDocument](/dotnet/framework/unmanaged-api/diagnostic Gets the language vendor of the current document. A representing the language vendor of the current document. - diff --git a/xml/System.Diagnostics.SymbolStore/SymDocumentType.xml b/xml/System.Diagnostics.SymbolStore/SymDocumentType.xml index 3325a98cd93..b30a9f7b6a1 100644 --- a/xml/System.Diagnostics.SymbolStore/SymDocumentType.xml +++ b/xml/System.Diagnostics.SymbolStore/SymDocumentType.xml @@ -55,8 +55,8 @@ is used when calling the method. - + The following example demonstrates how is used when calling the method. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics.SymbolStore/SymDocumentWriter.xml b/xml/System.Diagnostics.SymbolStore/SymDocumentWriter.xml index 643ed6cc7e8..d89bfc5e583 100644 --- a/xml/System.Diagnostics.SymbolStore/SymDocumentWriter.xml +++ b/xml/System.Diagnostics.SymbolStore/SymDocumentWriter.xml @@ -38,11 +38,11 @@ Provides methods for writing to a document referenced by a symbol store. - @@ -110,7 +110,7 @@ method to release resources. ]]> @@ -138,12 +138,12 @@ Use the method Releases the resources held by the current instance of the object. - method to release resources. - + ]]> @@ -211,11 +211,11 @@ Use the method to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -242,11 +242,11 @@ Use the method Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> diff --git a/xml/System.Diagnostics.SymbolStore/SymLanguageType.xml b/xml/System.Diagnostics.SymbolStore/SymLanguageType.xml index 780f1ba3205..c11aa8fb5da 100644 --- a/xml/System.Diagnostics.SymbolStore/SymLanguageType.xml +++ b/xml/System.Diagnostics.SymbolStore/SymLanguageType.xml @@ -55,8 +55,8 @@ is used when calling . - + The following code example demonstrates how is used when calling . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics.SymbolStore/SymLanguageVendor.xml b/xml/System.Diagnostics.SymbolStore/SymLanguageVendor.xml index 0bf9d925190..59a9f23236e 100644 --- a/xml/System.Diagnostics.SymbolStore/SymLanguageVendor.xml +++ b/xml/System.Diagnostics.SymbolStore/SymLanguageVendor.xml @@ -55,8 +55,8 @@ is used when calling . - + The following code example demonstrates how is used when calling . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics.SymbolStore/SymMethod.xml b/xml/System.Diagnostics.SymbolStore/SymMethod.xml index b048df5857e..c119f8fc78a 100644 --- a/xml/System.Diagnostics.SymbolStore/SymMethod.xml +++ b/xml/System.Diagnostics.SymbolStore/SymMethod.xml @@ -38,11 +38,11 @@ Represents a method within a symbol store. - class provides access only to the symbol-related attributes of a method, such as sequence points, lexical scopes, and parameter information. Use the classes to read the type-related attributes of a method. - + class provides access only to the symbol-related attributes of a method, such as sequence points, lexical scopes, and parameter information. Use the classes to read the type-related attributes of a method. + ]]> @@ -67,8 +67,8 @@ method instead of being created directly with this constructor. +## Remarks +Typically, instances of this type are obtained by calling the method instead of being created directly with this constructor. ]]> @@ -117,7 +117,7 @@ Typically, instances of this type are obtained by calling the method to release resources. ]]> @@ -145,12 +145,12 @@ Use the method to relea Releases the resources held by the current instance of the object. - method to release resources. - + ]]> @@ -218,11 +218,11 @@ Use the method to relea to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -249,11 +249,11 @@ Use the method to relea Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -357,11 +357,11 @@ Use the method to relea Gets the parameters for the current method. The array of parameters for the current method. - @@ -402,11 +402,11 @@ Use the method to relea Gets an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) offsets that a given position covers within this method. An array of start and end IL offset pairs. - @@ -443,11 +443,11 @@ Use the method to relea Returns the most enclosing lexical scope corresponding to an offset within a method. The most enclosing lexical scope for the given IL offset within the method. - method to start local variable searches. - + method to start local variable searches. + ]]> @@ -493,11 +493,11 @@ Use the method to relea The array of columns in the documents at which the sequence points end. Gets the sequence points for the current method and stores the information in the specified arrays. - object. Each element at a specific index of every array corresponds to a specific sequence point. The caller must supply pre-allocated arrays to hold the information to be returned. Any values in the arrays are overwritten. Use to retrieve the count of all sequence points and create arrays of the proper size. The sequence points are sorted by offset and are for all documents in the method. verifies the size of each array and places the sequence point information into each. If any array is `null`, the data for that array is not returned. - + object. Each element at a specific index of every array corresponds to a specific sequence point. The caller must supply pre-allocated arrays to hold the information to be returned. Any values in the arrays are overwritten. Use to retrieve the count of all sequence points and create arrays of the proper size. The sequence points are sorted by offset and are for all documents in the method. verifies the size of each array and places the sequence point information into each. If any array is `null`, the data for that array is not returned. + ]]> diff --git a/xml/System.Diagnostics.SymbolStore/SymReader.xml b/xml/System.Diagnostics.SymbolStore/SymReader.xml index 99e4d926bf6..4fd07304c00 100644 --- a/xml/System.Diagnostics.SymbolStore/SymReader.xml +++ b/xml/System.Diagnostics.SymbolStore/SymReader.xml @@ -60,8 +60,8 @@ method instead of being created directly with this constructor. +## Remarks +Typically, instances of this type are obtained by using the method instead of being created directly with this constructor. ]]> @@ -110,7 +110,7 @@ Typically, instances of this type are obtained by using the method to release resources. ]]> @@ -138,12 +138,12 @@ Use the method to relea Releases the resources held by the current instance. - method to release resources. - + ]]> @@ -211,11 +211,11 @@ Use the method to relea to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -242,11 +242,11 @@ Use the method to relea Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -289,11 +289,11 @@ Use the method to relea Gets a document specified by the URL for the document and optionally the language, language vendor, and type. The document with the specified URL if found in the symbol store, or if the document does not exist. - @@ -613,13 +613,13 @@ Use the method to relea The pointer to the input stream for the symbol store, or if using an on-disk store. Replaces the existing symbol store with a delta symbol store. - is much like the method, but the given delta acts as a complete replacement rather than an update. - - Only one of the parameters, `fileName` or `stream`, needs to be specified. If `fileName` is specified, the symbol store is updated with the symbols in that file. If `stream` is specified, the symbol store is updated with the data from the . - + is much like the method, but the given delta acts as a complete replacement rather than an update. + + Only one of the parameters, `fileName` or `stream`, needs to be specified. If `fileName` is specified, the symbol store is updated with the symbols in that file. If `stream` is specified, the symbol store is updated with the data from the . + ]]> @@ -654,13 +654,13 @@ Use the method to relea The pointer to the input stream for the symbol store, or if using an on-disk store. Updates the existing symbol store with a delta symbol store. - . - + . + ]]> @@ -691,11 +691,11 @@ Use the method to relea Gets the metadata token for the method that was specified as the user entry point for the module, if any. The metadata token for the method that is the user entry point for the module. - An entry point was not found. diff --git a/xml/System.Diagnostics.SymbolStore/SymScope.xml b/xml/System.Diagnostics.SymbolStore/SymScope.xml index 7a1830a7165..6121db3c6ef 100644 --- a/xml/System.Diagnostics.SymbolStore/SymScope.xml +++ b/xml/System.Diagnostics.SymbolStore/SymScope.xml @@ -38,11 +38,11 @@ Represents a lexical scope within , providing access to the start and end offsets of the scope, as well as its child and parent scopes. - class also provides access to all locals defined within the current scope. - + class also provides access to all locals defined within the current scope. + ]]> @@ -67,7 +67,7 @@ property to obtain instances of this class, instead of creating an instance by using this constructor. ]]> @@ -117,7 +117,7 @@ Typically, you use the method to release resources. ]]> @@ -145,12 +145,12 @@ Use the method to releas Releases the resources held by the current instance. - method to release resources. - + ]]> @@ -209,11 +209,11 @@ Use the method to releas to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -268,11 +268,11 @@ Use the method to releas Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -338,11 +338,11 @@ Use the method to releas Gets the local variables within the current lexical scope. The local variables within the current lexical scope. - There is insufficient memory to satisfy the request. diff --git a/xml/System.Diagnostics.SymbolStore/SymVariable.xml b/xml/System.Diagnostics.SymbolStore/SymVariable.xml index 9d1ab16c1af..74787bd91c1 100644 --- a/xml/System.Diagnostics.SymbolStore/SymVariable.xml +++ b/xml/System.Diagnostics.SymbolStore/SymVariable.xml @@ -38,11 +38,11 @@ Represents a variable within a symbol store. - object can be a parameter, a local variable, or a field. - + object can be a parameter, a local variable, or a field. + ]]> @@ -110,7 +110,7 @@ method to release resources. ]]> @@ -138,12 +138,12 @@ Use the method to rel Releases the resources held by the current instance. - method to release resources. - + ]]> @@ -175,11 +175,11 @@ Use the method to rel Gets the first address of a variable. The first address of the variable. - enumeration. - + enumeration. + ]]> @@ -211,11 +211,11 @@ Use the method to rel Gets the second address of a variable. The second address of the variable. - enumeration. - + enumeration. + ]]> @@ -247,11 +247,11 @@ Use the method to rel Gets the third address of a variable. The third address of the variable. - enumeration. - + enumeration. + ]]> @@ -367,11 +367,11 @@ Use the method to rel to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - and methods; do not call this method directly. - + and methods; do not call this method directly. + ]]> @@ -402,11 +402,11 @@ Use the method to rel Gets the end offset of a variable within the scope of the variable. The end offset of the variable. - @@ -433,11 +433,11 @@ Use the method to rel Releases unmanaged resources and performs other cleanup operations before the is reclaimed by garbage collection. - . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - + . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + ]]> @@ -527,11 +527,11 @@ Use the method to rel Gets the start offset of the variable within the scope of the variable. The start offset of the variable. - diff --git a/xml/System.Diagnostics.SymbolStore/SymWriter.xml b/xml/System.Diagnostics.SymbolStore/SymWriter.xml index 3a8837241c3..b9047e8f34d 100644 --- a/xml/System.Diagnostics.SymbolStore/SymWriter.xml +++ b/xml/System.Diagnostics.SymbolStore/SymWriter.xml @@ -482,7 +482,7 @@ Use the method to relea ## Remarks The `startOffset` and `endOffset` parameters are optional. If their value is zero, they are ignored and the variable is defined throughout the entire scope. If their value is nonzero, they fall within the offsets of the current scope. - You can call multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) + You can call multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.) ]]> @@ -640,7 +640,7 @@ Use the method to relea and methods; do not call this method directly. + This method is called only by the public and methods; do not call this method directly. ]]> @@ -671,7 +671,7 @@ Use the method to relea . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. ]]> @@ -745,7 +745,7 @@ Use the method to relea also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods are called. + also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods are called. ]]> @@ -1021,7 +1021,7 @@ Use the method to relea method is only associated with symbolic information and is not a metadata custom attribute. + The method is only associated with symbolic information and is not a metadata custom attribute. ]]> diff --git a/xml/System.Diagnostics.SymbolStore/SymbolToken.xml b/xml/System.Diagnostics.SymbolStore/SymbolToken.xml index dc2ca46049c..ee6c77e6e53 100644 --- a/xml/System.Diagnostics.SymbolStore/SymbolToken.xml +++ b/xml/System.Diagnostics.SymbolStore/SymbolToken.xml @@ -360,7 +360,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -410,7 +410,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Diagnostics.Tracing/EventAttribute.xml b/xml/System.Diagnostics.Tracing/EventAttribute.xml index eca00a3e433..b2fb02fedb2 100644 --- a/xml/System.Diagnostics.Tracing/EventAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventAttribute.xml @@ -63,7 +63,7 @@ -derived class, you must call the method on the base class, passing the event ID, followed by the same arguments as the defined method is passed. Follow the pattern shown in the examples. +When you apply this attribute to an ETW event method defined on an -derived class, you must call the method on the base class, passing the event ID, followed by the same arguments as the defined method is passed. Follow the pattern shown in the examples. ## Examples @@ -121,7 +121,7 @@ The following example shows how to use the constructor to specify events. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + The following example shows how to use the constructor to specify events. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet1"::: @@ -261,7 +261,7 @@ The following example shows how to use the should be greater than 0 or less than 65535 or errors can occur in a tracing operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. + should be greater than 0 or less than 65535 or errors can occur in a tracing operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. ]]> diff --git a/xml/System.Diagnostics.Tracing/EventCommandEventArgs.xml b/xml/System.Diagnostics.Tracing/EventCommandEventArgs.xml index 8844b939737..03805437e53 100644 --- a/xml/System.Diagnostics.Tracing/EventCommandEventArgs.xml +++ b/xml/System.Diagnostics.Tracing/EventCommandEventArgs.xml @@ -195,11 +195,11 @@ if is in range; otherwise, . - starting with `eventID` = 1 and continuing until returns `false`. - + starting with `eventID` = 1 and continuing until returns `false`. + ]]> @@ -251,11 +251,11 @@ if is in range; otherwise, . - starting with `eventID` = 1 and continuing until returns `false`. - + starting with `eventID` = 1 and continuing until returns `false`. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventDataAttribute.xml b/xml/System.Diagnostics.Tracing/EventDataAttribute.xml index 96ede279d22..a6fed77b4f5 100644 --- a/xml/System.Diagnostics.Tracing/EventDataAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventDataAttribute.xml @@ -58,11 +58,11 @@ Specifies a type to be passed to the method. - requires T to be an anonymous type or marked with the attribute. In addition, the properties of `T` must be a supported property type; either a simple framework type such as , , , , , or , or an array of primitive types. - + requires T to be an anonymous type or marked with the attribute. In addition, the properties of `T` must be a supported property type; either a simple framework type such as , , , , , or , or an array of primitive types. + ]]> @@ -146,11 +146,11 @@ Gets or sets the name to apply to an event if the event type or property is not explicitly named. The name to apply to the event or property. - , passing `null` for `eventName`, the event name is automatically derived from or determined based on the name of type `T`. - + , passing `null` for `eventName`, the event name is automatically derived from or determined based on the name of type `T`. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventIgnoreAttribute.xml b/xml/System.Diagnostics.Tracing/EventIgnoreAttribute.xml index e2e1c0b7312..817e2dafcb2 100644 --- a/xml/System.Diagnostics.Tracing/EventIgnoreAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventIgnoreAttribute.xml @@ -54,11 +54,11 @@ Specifies a property should be ignored when writing an event type with the method. - method is called, all of an object's public properties are written to the event payload. Apply to a property to prevent the property from being written in the event. - + method is called, all of an object's public properties are written to the event payload. Apply to a property to prevent the property from being written in the event. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventListener.xml b/xml/System.Diagnostics.Tracing/EventListener.xml index f6210fd3c2b..62426a0c056 100644 --- a/xml/System.Diagnostics.Tracing/EventListener.xml +++ b/xml/System.Diagnostics.Tracing/EventListener.xml @@ -65,25 +65,25 @@ Provides methods for enabling and disabling events from event sources. - object) implementations in the current application domain. When a new event listener is created, it is logically attached to all event sources in that application domain. - + object) implementations in the current application domain. When a new event listener is created, it is logically attached to all event sources in that application domain. + > [!NOTE] -> This type implements the interface. When you have finished using the type, you must dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - An event listener can enable or disable on a per-current event source basis by using event levels () and event keywords () to further restrict the set of events to be sent to the listener. The listener can also send arbitrary commands to a specific current event source by using the method. The meanings of the commands are specific to the implementation of the event source. - - Multiple event listeners can be defined in a single application domain. Each listener is logically independent of the other listeners so that events that are enabled or disabled by one listener affect only that listener. It is possible for commands sent with the method to do a semantic operation (such as a garbage collection or flushing data) that affects the other listeners, but this is the exception rather than the rule. - - Each event source keeps a list of event listeners that it sends events to. A set of filtering criteria is associated with each event source-listener pair. These criteria determine the events that listener will receive for the current event source. Listeners receive the events on their method. Therefore, subclasses of must override this method to do something useful with the data. - - When a new event source is created, the method is called. Every current event listener gets exactly one call for every current event source that can send it log messages. When an event listener is created, a series of calls are made to notify the new listener of all the event sources that existed before the listener was created. +> This type implements the interface. When you have finished using the type, you must dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + + An event listener can enable or disable on a per-current event source basis by using event levels () and event keywords () to further restrict the set of events to be sent to the listener. The listener can also send arbitrary commands to a specific current event source by using the method. The meanings of the commands are specific to the implementation of the event source. + + Multiple event listeners can be defined in a single application domain. Each listener is logically independent of the other listeners so that events that are enabled or disabled by one listener affect only that listener. It is possible for commands sent with the method to do a semantic operation (such as a garbage collection or flushing data) that affects the other listeners, but this is the exception rather than the rule. + + Each event source keeps a list of event listeners that it sends events to. A set of filtering criteria is associated with each event source-listener pair. These criteria determine the events that listener will receive for the current event source. Listeners receive the events on their method. Therefore, subclasses of must override this method to do something useful with the data. + + When a new event source is created, the method is called. Every current event listener gets exactly one call for every current event source that can send it log messages. When an event listener is created, a series of calls are made to notify the new listener of all the event sources that existed before the listener was created. > [!IMPORTANT] -> When instantiating an `EventListener`, the callbacks to and can happen _before_ the constructor has completed. Take care when you initialize instance members used in those callbacks. - +> When instantiating an `EventListener`, the callbacks to and can happen _before_ the constructor has completed. Take care when you initialize instance members used in those callbacks. + ]]> @@ -130,11 +130,11 @@ Creates a new instance of the class. - methods to enable events. - + methods to enable events. + ]]> @@ -232,13 +232,13 @@ Releases the resources used by the current instance of the class. - . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> @@ -463,11 +463,11 @@ Occurs when an event source ( object) is attached to the dispatcher. - occurs for all existing event sources when the event listener is created, as well as for any event sources that are created after the event listener's creation. - + occurs for all existing event sources when the event listener is created, as well as for any event sources that are created after the event listener's creation. + ]]> @@ -522,11 +522,11 @@ Gets a small non-negative number that represents the specified event source. A small non-negative number that represents the specified event source. - identifies an event source that is suitable for indexing an array. This integer is unique within the application domain. An event listener might find it useful to store additional information about each event source that is connected to it. The value returned by allows this extra information to be efficiently stored in an expandable array such as `List`. - + identifies an event source that is suitable for indexing an array. This integer is unique within the application domain. An event listener might find it useful to store additional information about each event source that is connected to it. The value returned by allows this extra information to be efficiently stored in an expandable array such as `List`. + ]]> @@ -621,13 +621,13 @@ The event source. Called for all existing event sources when the event listener is created and when a new event source is attached to the listener. - callbacks to occur before the callback. - + callbacks to occur before the callback. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 8f96a4e4315..7108c851106 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -326,7 +326,7 @@ , method. + Traits provide additional information for an event and are interpreted by an event listener. Traits are specified as key-value pairs and if not specified in pairs, an exception will occur. You can retrieve a trait by passing the key to the , method. Specifying `settings` when the is constructed enables you to specify whether the event is written in a manifest-based or a self-describing format. In addition, you can specify that an exception should be raised when an error occurs during the event-writing process. @@ -482,7 +482,7 @@ , method. + Traits provide additional information for an event and are interpreted by an event listener. Traits are specified as key-value pairs and if not specified in pairs, an exception will occur. You can retrieve a trait by passing the key to the , method. Specifying `config` when the is constructed enables you to specify whether the event is written in a manifest-based or a self-describing format. In addition, you can specify that an exception should be raised when an error occurs during the event-writing process. @@ -582,7 +582,7 @@ constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. + constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. ]]> @@ -1025,7 +1025,7 @@ returns `null`. + If `flags` specifies `OnlyIfNeededForRegistration` and the `eventSourceType` specified does not require explicit registration, returns `null`. ]]> @@ -1617,7 +1617,7 @@ In such cases, the GUID that is used to register the forwards the command to the callback. What the does with the command and its arguments is specific to the event source. The command and command arguments are passed to the callback of the specified event source. If possible, the current event source should not affect other event listeners' filtering events; however, that may not be possible if the command causes a garbage collection, a system flush, or some other global activity. + Calling forwards the command to the callback. What the does with the command and its arguments is specific to the event source. The command and command arguments are passed to the callback of the specified event source. If possible, the current event source should not affect other event listeners' filtering events; however, that may not be possible if the command causes a garbage collection, a system flush, or some other global activity. ]]> @@ -1688,7 +1688,7 @@ In such cases, the GUID that is used to register the method sets the activity ID on a per-thread basis. All events on the thread will have that activity ID until a new activity is started on the same thread. + Calling the method sets the activity ID on a per-thread basis. All events on the thread will have that activity ID until a new activity is started on the same thread. This method is called only by libraries that manage their own threads. @@ -1751,7 +1751,7 @@ In such cases, the GUID that is used to register the method to temporarily overwrite the current thread's activity ID with a new activity ID. You must then restore the previous activity ID by passing the `oldActivityThatWillContinue` argument to the method. + You can call the method to temporarily overwrite the current thread's activity ID with a new activity ID. You must then restore the previous activity ID by passing the `oldActivityThatWillContinue` argument to the method. ]]> @@ -2041,7 +2041,7 @@ In such cases, the GUID that is used to register the ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. + If `eventName` is `null`, the event name is automatically derived from the type T's event data () or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. ]]> @@ -2126,7 +2126,7 @@ In such cases, the GUID that is used to register the ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. + If `eventName` is `null`, the event name is automatically derived from the type T's event data () or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. ]]> @@ -2211,7 +2211,7 @@ In such cases, the GUID that is used to register the ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. + If `eventName` is `null`, the event name is automatically derived from the type T's event data () or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. ]]> @@ -2300,7 +2300,7 @@ In such cases, the GUID that is used to register the ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. + If `eventName` is `null`, the event name is automatically derived from the type T's event data () or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. ]]> @@ -2320,11 +2320,11 @@ In such cases, the GUID that is used to register the overload, which is considerably slower than the other overloads. See the overload page for details. + The `WriteEvent` method provides overloads with combinations of string and integer arguments. If none of these combinations match the parameters for the call, the compiler uses the overload, which is considerably slower than the other overloads. See the overload page for details. In all cases, the `eventid` parameter should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2334,7 +2334,7 @@ public void Info1(string arg1) } ``` - You can also create a custom overload by using the method. + You can also create a custom overload by using the method. > [!IMPORTANT] > Event parameters with a type of `string` should not include `\0` characters. They are unsupported characters and can cause issues for parsers of the event payload. @@ -2399,7 +2399,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2477,7 +2477,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2590,7 +2590,7 @@ public void Info1(byte[] arg1) `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. -When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. +When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2669,7 +2669,7 @@ public void Info1(int arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2765,11 +2765,11 @@ public void Info1(string arg1) 4. It calls the function, which then determines the type of each argument so it can be serialized for ETW. - The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. + The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2842,7 +2842,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2923,7 +2923,7 @@ The following example shows how to use this method overload to write an event. T ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3052,7 +3052,7 @@ public void Info1(int arg1, int arg2, int arg3) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3126,7 +3126,7 @@ public void Info1(Int64 arg1, Byte[] arg2) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3199,7 +3199,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that's identified as an ETW event in an -derived class, you must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that's identified as an ETW event in an -derived class, you must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3274,7 +3274,7 @@ public void Info1(Int64 arg1, string arg2) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3349,7 +3349,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3424,7 +3424,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3500,7 +3500,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3576,7 +3576,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3653,7 +3653,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3730,7 +3730,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. + When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -3811,9 +3811,9 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - This protected method enables users to define new overloads that are faster than the provided overloads. Creating a new overload involves unsafe code. The basic procedure is to stack-allocate an array of event data descriptors that matches the number of payload items. For each payload item, set the correct size and value in the event data array.Call with the initialized array. + This protected method enables users to define new overloads that are faster than the provided overloads. Creating a new overload involves unsafe code. The basic procedure is to stack-allocate an array of event data descriptors that matches the number of payload items. For each payload item, set the correct size and value in the event data array.Call with the initialized array. - The following example shows how to add a overload that accepts four arguments. An example would be if you have a logging event that logs a string and 3 integers. + The following example shows how to add a overload that accepts four arguments. An example would be if you have a logging event that logs a string and 3 integers. ```csharp [Event(1)] @@ -3823,7 +3823,7 @@ public void LogTime(string tag, int hour, int minute, int second) } ``` - You could do this without calling , but it would be slower than it needs to be. That is because it uses arrays and reflection to figure out what to do. If you log these at a high rate (> 1000 / sec), it can be worth making a fast helper, as shown in the following example. The method shadows the existing . Thus the original caller code (LogTime) does not actually change, but the C# compiler will use the more specialized version which will be faster. + You could do this without calling , but it would be slower than it needs to be. That is because it uses arrays and reflection to figure out what to do. If you log these at a high rate (> 1000 / sec), it can be worth making a fast helper, as shown in the following example. The method shadows the existing . Thus the original caller code (LogTime) does not actually change, but the C# compiler will use the more specialized version which will be faster. To compile unsafe code, you must specify the [/unsafe (C# Compiler Options)](/dotnet/csharp/language-reference/compiler-options/unsafe-compiler-option) compiler option. @@ -4034,19 +4034,19 @@ fixed(byte* ptr = arg) method logs a transfer event. The activity of the current thread is logged with the event, and this allows two activities to be related by a consumer of events. + The method logs a transfer event. The activity of the current thread is logged with the event, and this allows two activities to be related by a consumer of events. Your ETW event method calling this function must follow these guidelines: - Specify the first parameter as a named `relatedActivityId`. - Specify either or as the property. -- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. +- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. If `args` is not used, it is converted to an empty array for the resulting call to ETW. ## Examples -The following code example shows how you might can specify an event source that calls . +The following code example shows how you might can specify an event source that calls . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/module1.vb" id="Snippet1"::: @@ -4128,19 +4128,19 @@ The following code example shows how you might can specify an event source that is similar to the method but offers better performance, because it does not have to unbox the `childActivityID` and `data` arguments. + is similar to the method but offers better performance, because it does not have to unbox the `childActivityID` and `data` arguments. Your ETW event method calling this function must follow these guidelines: - Specify the first parameter as a named `relatedActivityId`. - Specify either or as the property. -- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. +- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. - This method uses the same rules as for the `args` parameter. See WriteEventCore documentation for more details. + This method uses the same rules as for the `args` parameter. See WriteEventCore documentation for more details. ## Examples -The following C# code example shows how to define a method overload that calls . +The following C# code example shows how to define a method overload that calls . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/module1.vb" id="Snippet5"::: diff --git a/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml b/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml index 3dd12ff1d6b..b9cc92eacd1 100644 --- a/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml @@ -210,7 +210,7 @@ constructor that will read the resources. This name is the value of the property. If the property is not `null`, the object looks up the localized strings for events by using the following resource naming scheme, where the terms in uppercase represent the name of the event, task, keyword, or map value that should be localized: + Event sources support the localization of events. You can localize the names used for events, operation codes, tasks, keywords, and maps to multiple languages. To localize events, create a .ResX style string table by adding a resource file to your project. The resource file is given a name (for example, DefaultNameSpace.ResourceFileName) that can be passed to the constructor that will read the resources. This name is the value of the property. If the property is not `null`, the object looks up the localized strings for events by using the following resource naming scheme, where the terms in uppercase represent the name of the event, task, keyword, or map value that should be localized: - event_EVENTNAME diff --git a/xml/System.Diagnostics.Tracing/PollingCounter.xml b/xml/System.Diagnostics.Tracing/PollingCounter.xml index fa46ceade35..aab46d09852 100644 --- a/xml/System.Diagnostics.Tracing/PollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/PollingCounter.xml @@ -47,15 +47,15 @@ Provides a variant of that collects and calculates similar statistics as . - is a variant of that uses a callback method to poll for values rather than requiring the writer to explicitly call each time a value is tracked, `metricProvider` is a callback method that polls for values. The instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener. + is a variant of that uses a callback method to poll for values rather than requiring the writer to explicitly call each time a value is tracked, `metricProvider` is a callback method that polls for values. The instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener. A lives as long as the that it is attached to unless it is explicitly disposed. -`PollingCounter` differs from in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. +`PollingCounter` differs from in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. For an example that uses inside the runtime for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index f75e3cbd363..a5bcf373cc2 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -59,11 +59,11 @@ An `Activity` has an operation name, an ID, a start time and duration, tags, and The current activity can be accessed with the static property. -Activities should be created by calling the constructor, configured as necessary, and then started with the method, which maintains parent-child relationships for the activities and sets . +Activities should be created by calling the constructor, configured as necessary, and then started with the method, which maintains parent-child relationships for the activities and sets . When an activity is finished, it should be stopped with the method. -However, if you dispose the `Activity` object, that stops it so you don't need to explicitly call . That simplifies the coding pattern. For more information, see the method. +However, if you dispose the `Activity` object, that stops it so you don't need to explicitly call . That simplifies the coding pattern. For more information, see the method. No `Activity` methods allow exceptions to escape as a response to bad inputs. They are thrown and caught (which allows debuggers and monitors to see the error), but the exception is suppressed, and the operation does something reasonable (typically it does nothing). @@ -187,7 +187,7 @@ Note that has a "builder" pattern: you call t ## Remarks -This key/value pair is included in the collection returned by the property, and can also be retrieved by the method. +This key/value pair is included in the collection returned by the property, and can also be retrieved by the method. `Baggage` is meant for information that is needed for runtime control. For information that is useful to show up in the log with the , use the property. @@ -1121,7 +1121,7 @@ An ID has a hierarchical structure: `root-id.id1_id2.id3_`. The ID is generated ## Remarks -The best practice for the library authors is not try to set this property. This property is automatically set when creating the Activity. The setter is useful only in the case of Activity objects created using the Activity constructor and want to override the default value. Activity objects created using automatically have this property set to the right value. +The best practice for the library authors is not try to set this property. This property is automatically set when creating the Activity. The setter is useful only in the case of Activity objects created using the Activity constructor and want to override the default value. Activity objects created using automatically have this property set to the right value. ]]> @@ -1652,7 +1652,7 @@ The specified format will take precedence over `Parent.IdFormat`, the from another process logically started this . The `parentId` brings up the (as well as the property) and can be used to reconstruct the causal tree. -- This method is only intended for use with Activities created from the Activity constructor. Activities created by calling or already have the parent ID set, and invoking this method has no effect. +- This method is only intended for use with Activities created from the Activity constructor. Activities created by calling or already have the parent ID set, and invoking this method has no effect. - This method should only be used before starting the object. This method has no effect if you call it after the object has started. ]]> @@ -1873,7 +1873,7 @@ When passing code value different than ActivityStatusCode.Error, the Activity.St ## Remarks -All activities created from public constructors will have a singleton source where the source name is an empty string. Otherwise, the source will hold the object that created the activity through . +All activities created from public constructors will have a singleton source where the source name is an empty string. Otherwise, the source will hold the object that created the activity through . ]]> @@ -1950,7 +1950,7 @@ Calling the `Start` method does the following: - If was not set previously, sets it to . - Generates a unique for this activity. -Use to start the and write the start event. +Use to start the and write the start event. ]]> @@ -1991,7 +1991,7 @@ Use is called, but it can be set at any time by calling . +The `StartTimeUtc` property is typically initialized when is called, but it can be set at any time by calling . ]]> @@ -2094,7 +2094,7 @@ Calling the `Stop` method: - Sets to . - If the end time was not set previously, sets as the difference between and . -Call to stop the and write the stop event. +Call to stop the and write the stop event. ]]> diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index 626aeac4a66..40cb26d9189 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -76,7 +76,7 @@ For .NET Framework apps only, you can also enable or disable a ``` - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/BooleanSwitch/Overview/remarks.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/BooleanSwitch/Overview/remarks.vb" id="Snippet2"::: @@ -322,7 +322,7 @@ For .NET Framework apps, the pro . + By default, this field is set to `false` (disabled). To enable the switch, assign this field the value of `true`. To disable the switch, assign the value to `false`. The value of this property is determined by the value of the base class property . ## Examples The following code example creates a and uses the switch to determine whether to print an error message. The switch is created at the class level. The `Main` method passes its location to `MyMethod`, which prints an error message and the location where the error occurred. @@ -382,7 +382,7 @@ For .NET Framework apps, the pro method determines whether the new value is a valid string representation of a Boolean value ("false" or "true"). If so, the method sets the property to 0 or 1. Otherwise, the base method is called, which converts the string value to an integer value, which is then used to set the property. + The method determines whether the new value is a valid string representation of a Boolean value ("false" or "true"). If so, the method sets the property to 0 or 1. Otherwise, the base method is called, which converts the string value to an integer value, which is then used to set the property. ]]> diff --git a/xml/System.Diagnostics/ConditionalAttribute.xml b/xml/System.Diagnostics/ConditionalAttribute.xml index aaa43ad2331..d37acea6b2a 100644 --- a/xml/System.Diagnostics/ConditionalAttribute.xml +++ b/xml/System.Diagnostics/ConditionalAttribute.xml @@ -173,7 +173,7 @@ constructor. This example is part of a larger example provided for the class. + The following example demonstrates how to use the constructor. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ConditionalAttribute/Overview/cas.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ConditionalAttribute/Overview/cas.vb" id="Snippet8"::: diff --git a/xml/System.Diagnostics/ConsoleTraceListener.xml b/xml/System.Diagnostics/ConsoleTraceListener.xml index 8da07c0e0cf..4a880da2ff9 100644 --- a/xml/System.Diagnostics/ConsoleTraceListener.xml +++ b/xml/System.Diagnostics/ConsoleTraceListener.xml @@ -32,17 +32,17 @@ class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. + Use the class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. + When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. > [!NOTE] > If the console does not exist, as in a Windows-based application, messages written to the console are not displayed. - Add a object to the appropriate collection if you want messages written through , , or to be written to the console. In addition, you can write messages directly to the console using the or methods. + Add a object to the appropriate collection if you want messages written through , , or to be written to the console. In addition, you can write messages directly to the console using the or methods. > [!NOTE] > The and classes share the same collection, accessed through their respective `Listeners` properties. If you add a object to the collection using one of these classes, the other class automatically uses the same listener. @@ -53,11 +53,11 @@ - To enable tracing in C#, add the **/d:TRACE** flag to the compiler command line when you compile your code, or add **#define TRACE** to the top of your file. In Visual Basic, add the **/d:TRACE=True** flag to the compiler command line. - You can add a object to the collection in your code. Or, for .NET Framework apps, you can add a object to the collection through the application configuration file. Add the object in your code to write messages for a specific code section or execution path. Add the object in your application configuration file to direct all trace and debug messages to the console while the application executes. + You can add a object to the collection in your code. Or, for .NET Framework apps, you can add a object to the collection through the application configuration file. Add the object in your code to write messages for a specific code section or execution path. Add the object in your application configuration file to direct all trace and debug messages to the console while the application executes. - To write trace and debug messages to the console for a specific section of code, initialize a object and add it to the collection. Instrument the section of code that contains messages using the or classes. At the end of the code section, remove the object from the collection, and call the method on the . + To write trace and debug messages to the console for a specific section of code, initialize a object and add it to the collection. Instrument the section of code that contains messages using the or classes. At the end of the code section, remove the object from the collection, and call the method on the . -For .NET Framework apps, to direct all trace and debug messages to the console while the application executes, add a object to the application configuration file. The following example adds a object named `configConsoleListener` to the collection. +For .NET Framework apps, to direct all trace and debug messages to the console while the application executes, add a object to the application configuration file. The following example adds a object named `configConsoleListener` to the collection. ```xml @@ -132,7 +132,7 @@ For .NET Framework apps, to direct all trace and debug messages to the console w object to write messages to the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to the stream. Its property is initialized to an empty string (""). @@ -189,7 +189,7 @@ For .NET Framework apps, to direct all trace and debug messages to the console w object to write messages to either the or the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to either the or the stream. Its property is initialized to an empty string (""). @@ -244,7 +244,7 @@ For .NET Framework apps, to direct all trace and debug messages to the console w instance (either the stream or the stream) is closed. + The stream specified for this instance (either the stream or the stream) is closed. ]]> diff --git a/xml/System.Diagnostics/CorrelationManager.xml b/xml/System.Diagnostics/CorrelationManager.xml index 9586c2429a3..fbb2cd419a9 100644 --- a/xml/System.Diagnostics/CorrelationManager.xml +++ b/xml/System.Diagnostics/CorrelationManager.xml @@ -56,7 +56,7 @@ ## Remarks Traces generated from a single logical operation can be tagged with an operation-unique identity, in order to distinguish them from traces from a different logical operation. For example, it may be useful to group correlated traces by ASP.NET request. The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. - Logical operations can also be nested. The property exposes the stack of nested logical operation identities. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity off the stack. + Logical operations can also be nested. The property exposes the stack of nested logical operation identities. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity off the stack. > [!NOTE] > Logical operation identities are objects, allowing the use of a type for a logical operation identity. @@ -115,7 +115,7 @@ property gets and sets the global activity identity in the for the thread. The is used for trace transfer operations in trace listeners that override the method, such as the class. + The property gets and sets the global activity identity in the for the thread. The is used for trace transfer operations in trace listeners that override the method, such as the class. ]]> @@ -169,7 +169,7 @@ method pushes a new logical operation identity onto the property's stack. Each call to the method pops a logical operation identity from the stack. + Each call to the method pushes a new logical operation identity onto the property's stack. Each call to the method pops a logical operation identity from the stack. ]]> @@ -283,7 +283,7 @@ ## Examples - The following code example demonstrates the use of the method by initializing a logical operation to be associated with the main thread. For the complete code example, see the class. + The following code example demonstrates the use of the method by initializing a logical operation to be associated with the main thread. For the complete code example, see the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CorrelationManager/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CorrelationManager/Overview/module1.vb" id="Snippet2"::: diff --git a/xml/System.Diagnostics/CounterCreationData.xml b/xml/System.Diagnostics/CounterCreationData.xml index ad5bda09c54..14660f2f3cb 100644 --- a/xml/System.Diagnostics/CounterCreationData.xml +++ b/xml/System.Diagnostics/CounterCreationData.xml @@ -109,7 +109,7 @@ class. Because the example does not pass in any parameters, the , , and properties are not specified and must be defined later. + The following code example shows how to create an empty instance of the class. Because the example does not pass in any parameters, the , , and properties are not specified and must be defined later. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet3"::: @@ -161,7 +161,7 @@ class, and pass in parameters to set the , and properties of the object when it is initialized. + The following code example shows how to create an instance of the class, and pass in parameters to set the , and properties of the object when it is initialized. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet2"::: @@ -226,7 +226,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet5"::: @@ -301,7 +301,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet4"::: @@ -365,7 +365,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet6"::: diff --git a/xml/System.Diagnostics/CounterCreationDataCollection.xml b/xml/System.Diagnostics/CounterCreationDataCollection.xml index b3397b2cc26..6b2b7adbc5d 100644 --- a/xml/System.Diagnostics/CounterCreationDataCollection.xml +++ b/xml/System.Diagnostics/CounterCreationDataCollection.xml @@ -45,7 +45,7 @@ ## Examples The following example demonstrates how to use the class. The example creates a new instance of the class and uses several methods to add statements to the collection, return their index, and add or remove attributes at a specific index point. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -233,7 +233,7 @@ method to add a object to a . + The following example demonstrates how to use the method to add a object to a . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -334,7 +334,7 @@ method overload to add objects from one to another . + The following example demonstrates how to use the method overload to add objects from one to another . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationDataCollection/AddRange/countercreationdatacollection_addrange.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationDataCollection/AddRange/countercreationdatacollection_addrange.vb" id="Snippet2"::: @@ -386,7 +386,7 @@ method to find a object in a . + The following example demonstrates how to use the method to find a object in a . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationDataCollection/Contains/countercreationdatacollection_contains.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationDataCollection/Contains/countercreationdatacollection_contains.vb" id="Snippet1"::: @@ -480,7 +480,7 @@ entries from a and uses the method to display their names and indexes. + The following example retrieves entries from a and uses the method to display their names and indexes. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationDataCollection/IndexOf/countercreationdatacollection_insert_indexof.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationDataCollection/IndexOf/countercreationdatacollection_insert_indexof.vb" id="Snippet1"::: @@ -530,7 +530,7 @@ method to insert a object into a . + The following example demonstrates how to use the method to insert a object into a . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationDataCollection/IndexOf/countercreationdatacollection_insert_indexof.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationDataCollection/IndexOf/countercreationdatacollection_insert_indexof.vb" id="Snippet1"::: @@ -671,7 +671,7 @@ method determines whether the object specified in the `value` parameter is a instance. If not, it throws an . + The method determines whether the object specified in the `value` parameter is a instance. If not, it throws an . ]]> @@ -720,7 +720,7 @@ method to delete a object from the . + The following example demonstrates how to use the method to delete a object from the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationDataCollection/Contains/countercreationdatacollection_contains.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationDataCollection/Contains/countercreationdatacollection_contains.vb" id="Snippet2"::: diff --git a/xml/System.Diagnostics/CounterSample.xml b/xml/System.Diagnostics/CounterSample.xml index 3b68ca7fef9..a8ae58edcb7 100644 --- a/xml/System.Diagnostics/CounterSample.xml +++ b/xml/System.Diagnostics/CounterSample.xml @@ -118,7 +118,7 @@ method for the first time. + Use this constructor to take an initial sample of the performance counter. The System Monitor supplies values for these parameters automatically when you call the method for the first time. ]]> @@ -180,7 +180,7 @@ method. + Use this constructor to take samples after you have already taken an initial sample of the performance counter. The System Monitor supplies values for these parameters automatically when you call the method. @@ -698,7 +698,7 @@ ## Remarks Two structures are equal if they have identical property values. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -746,7 +746,7 @@ ## Remarks Two structures are not equal if any of their property values are different. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> diff --git a/xml/System.Diagnostics/CounterSampleCalculator.xml b/xml/System.Diagnostics/CounterSampleCalculator.xml index 2ba9c31ef70..2c64231a41b 100644 --- a/xml/System.Diagnostics/CounterSampleCalculator.xml +++ b/xml/System.Diagnostics/CounterSampleCalculator.xml @@ -89,7 +89,7 @@ method overload returns meaningful results only for performance counters of the following : + The method overload returns meaningful results only for performance counters of the following : - @@ -149,8 +149,8 @@ method overload to calculate the value of two raw counter samples. - + The following example demonstrates the use of the method overload to calculate the value of two raw counter samples. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/DataReceivedEventArgs.xml b/xml/System.Diagnostics/DataReceivedEventArgs.xml index 5858d6c57bd..0a79dddd4fd 100644 --- a/xml/System.Diagnostics/DataReceivedEventArgs.xml +++ b/xml/System.Diagnostics/DataReceivedEventArgs.xml @@ -55,14 +55,14 @@ or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. + To asynchronously collect the redirected or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. ## Examples - The following code example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. + The following code example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. - The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.vb" id="Snippet1"::: @@ -125,16 +125,16 @@ or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. + When you redirect the or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. - When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. + When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. ## Examples - The following code example illustrates a simple event handler associated with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + The following code example illustrates a simple event handler associated with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/datareceivedevent.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DataReceivedEventArgs/Overview/datareceivedevent.vb" id="Snippet4"::: diff --git a/xml/System.Diagnostics/DataReceivedEventHandler.xml b/xml/System.Diagnostics/DataReceivedEventHandler.xml index 3944f22dc00..d679176e422 100644 --- a/xml/System.Diagnostics/DataReceivedEventHandler.xml +++ b/xml/System.Diagnostics/DataReceivedEventHandler.xml @@ -59,14 +59,14 @@ ## Remarks When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. + To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. ## Examples - The following code example illustrates how to perform asynchronous read operations on the redirected stream of the **sort** command. The **sort** command is a console application that reads and sorts text input. + The following code example illustrates how to perform asynchronous read operations on the redirected stream of the **sort** command. The **sort** command is a console application that reads and sorts text input. - The example creates a delegate for the `SortOutputHandler` event handler and associates the delegate with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + The example creates a delegate for the `SortOutputHandler` event handler and associates the delegate with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index 0828fef1233..70ac9a0bf30 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -75,23 +75,23 @@ To make your code more robust without impacting the performance and code size of your shipping product, use methods in the class to print debugging information and check your logic with assertions. - This class provides methods to display an dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: + This class provides methods to display an dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: -- -- -- -- +- +- +- +- The and classes provide means to dynamically control the tracing output. For .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in .NET Framework apps, see the class and the [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches) article. - You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, the class emits trace output. + You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, the class emits trace output. > [!NOTE] -> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and can't be enumerated in this article. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. +> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and can't be enumerated in this article. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. - You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. + You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. -For .NET Framework apps, you can set the and for by editing your app's configuration file. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can set the and for by editing your app's configuration file. The configuration file should be formatted as shown in the following example. ```xml @@ -110,7 +110,7 @@ For .NET Framework apps, you can set the to indicate the beginning and end of a program's execution. The example also uses and to distinguish the tracing output. +The following example uses to indicate the beginning and end of a program's execution. The example also uses and to distinguish the tracing output. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Overview/source.vb" id="Snippet1"::: @@ -209,9 +209,9 @@ The following example uses to indicate the begin method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. @@ -219,7 +219,7 @@ The following example uses to indicate the begin > Windows 8.x apps do not support modal dialog boxes, so they behave the same in user interface mode and non-user interface mode. The message is written to the active trace listeners in debugging mode, or no message is written in release mode. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -233,7 +233,7 @@ For .NET Framework apps, you can change the behavior of the to confirm that the index value is valid. If it is not valid, outputs the call stack. +The following example creates an index for an array, performs some action to set the value of the index, and then calls to confirm that the index value is valid. If it is not valid, outputs the call stack. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Assert/source.vb" id="Snippet1"::: @@ -314,14 +314,14 @@ The following example creates an index for an array, performs some action to set This overload was introduced in .NET 6 to improve performance. In comparison to the overloads that take a `String` parameter, this overload only evaluates any interpolated string formatting items if the message is required. - By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -420,14 +420,14 @@ For .NET Framework apps, you can change the behavior of the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -441,7 +441,7 @@ For .NET Framework apps, you can change the behavior of the outputs a message. +The following example checks whether the `type` parameter is valid. If `type` is `null`, outputs a message. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Assert/source1.vb" id="Snippet1"::: @@ -531,14 +531,14 @@ The following example checks whether the `type` parameter is valid. If `type` is This overload was introduced in .NET 6 to improve performance. In comparison to the overloads that take a `String` parameter, this overload only evaluates any interpolated string formatting items if the message is required. - By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -629,14 +629,14 @@ For .NET Framework apps, you can change the behavior of the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -650,7 +650,7 @@ For .NET Framework apps, you can change the behavior of the outputs two messages. +The following example checks whether the `type` parameter is valid. If `type` is `null`, outputs two messages. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Assert/source2.vb" id="Snippet1"::: @@ -760,16 +760,16 @@ The following example checks whether the `type` parameter is valid. If `type` is collection. + This method uses the [.NET composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an object to its text representation and embed that representation in a string. The resulting string is sent to the collection. - By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -834,9 +834,9 @@ For .NET Framework apps, you can change the behavior of the or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. -For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. ```xml @@ -912,7 +912,7 @@ For .NET Framework apps, you can also set the . - Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ## Examples @@ -1004,23 +1004,23 @@ The following example creates a outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. + The default behavior is that the outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can customize this behavior by adding a to, or removing one from, the collection. + You can customize this behavior by adding a to, or removing one from, the collection. ## Examples -The following example uses the method to print a message during exception handling. +The following example uses the method to print a message during exception handling. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Fail/source.vb" id="Snippet1"::: - You can also use the method in a switch statement. + You can also use the method in a switch statement. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Fail/source.vb" id="Snippet2"::: @@ -1100,23 +1100,23 @@ The following example uses the method to outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. + The default behavior is that the outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can customize this behavior by adding a to, or removing one from, the collection. + You can customize this behavior by adding a to, or removing one from, the collection. ## Examples -The following example uses the method to print a message during exception handling. +The following example uses the method to print a message during exception handling. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Fail/source1.vb" id="Snippet1"::: -You can also use the method in a switch statement. +You can also use the method in a switch statement. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Fail/source1.vb" id="Snippet2"::: @@ -1185,7 +1185,7 @@ You can also use the method in a switch or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. @@ -1329,7 +1329,7 @@ End of list of errors ## Remarks -The property represents the number of times the indent of size is applied. +The property represents the number of times the indent of size is applied. ## Examples @@ -1408,7 +1408,7 @@ End of list of errors ## Remarks A interprets this number as spaces. An ignores this value. -For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. +For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. ```xml @@ -1464,14 +1464,14 @@ For .NET Framework apps, you can also set the class. To remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the . To redirect output to a file or stream, add an instance of the . + The listeners produce formatted output from the debug output. By default, the collection contains an instance of the class. To remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the . To redirect output to a file or stream, add an instance of the . > [!NOTE] -> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. +> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. ## Examples -The following example creates a that outputs to the console screen. The code then adds the new listener to the . +The following example creates a that outputs to the console screen. The code then adds the new listener to the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Listeners/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Debug/Listeners/source.vb" id="Snippet1"::: @@ -1798,13 +1798,13 @@ End of list of errors ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -1882,13 +1882,13 @@ The following example creates a named `gen ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -1970,13 +1970,13 @@ The following example creates a named `gen Use the `category` parameter to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2058,13 +2058,13 @@ The following example creates a named `gen Use the `category` parameter to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2155,7 +2155,7 @@ This overload was introduced in .NET 6 to improve performance. In comparison to Use the `category` parameter to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -2230,13 +2230,13 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. A line terminator follows the second message. @@ -2332,13 +2332,13 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information about adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information about adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2436,7 +2436,7 @@ This overload was introduced in .NET 6 to improve performance. In comparison to Use the `category` parameter to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -2515,13 +2515,13 @@ This overload was introduced in .NET 6 to improve performance. In comparison to The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2621,13 +2621,13 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2733,13 +2733,13 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. A line terminator follows the second message. @@ -2818,13 +2818,13 @@ The following example creates a named `gen ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2906,13 +2906,13 @@ The following example creates a named `gen The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -3009,11 +3009,11 @@ The following example creates a named `gen ## Remarks This method uses the [.NET composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an object to its text representation and embed that representation in a string. - The [params](/dotnet/csharp/language-reference/keywords/params) (in C#) or [ParamArray](/dotnet/visual-basic/language-reference/modifiers/paramarray) (in Visual Basic) keyword in the syntax for this method implies that the object array can be a single value. The exception to this is the object. Explicit overloads take precedence, so an `arg` value of a single string will default to the overload. + The [params](/dotnet/csharp/language-reference/keywords/params) (in C#) or [ParamArray](/dotnet/visual-basic/language-reference/modifiers/paramarray) (in Visual Basic) keyword in the syntax for this method implies that the object array can be a single value. The exception to this is the object. Explicit overloads take precedence, so an `arg` value of a single string will default to the overload. By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -3082,13 +3082,13 @@ The following example creates a named `gen The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. A line terminator follows the second message. @@ -3176,7 +3176,7 @@ This overload was introduced in .NET 6 to improve performance. In comparison to By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -3251,13 +3251,13 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. A line terminator follows the second message. @@ -3354,13 +3354,13 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information about adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information about adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -3458,7 +3458,7 @@ This overload was introduced in .NET 6 to improve performance. In comparison to The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -3536,13 +3536,13 @@ This overload was introduced in .NET 6 to improve performance. In comparison to The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -3642,13 +3642,13 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside of the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. A line terminator follows the second message. diff --git a/xml/System.Diagnostics/DebuggableAttribute.xml b/xml/System.Diagnostics/DebuggableAttribute.xml index 9f660fe8abf..b3fbb780332 100644 --- a/xml/System.Diagnostics/DebuggableAttribute.xml +++ b/xml/System.Diagnostics/DebuggableAttribute.xml @@ -68,7 +68,7 @@ A debugger might choose to ignore the settings when loading an assembly. However, attaching a debugger to a running program may prevent the debugger from changing the settings because they have already been applied. - To use the with dynamic assemblies using the Reflection Emit methods, emit the before calling the methods to ensure that the settings are applied to the entire assembly. + To use the with dynamic assemblies using the Reflection Emit methods, emit the before calling the methods to ensure that the settings are applied to the entire assembly. For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). @@ -135,7 +135,7 @@ constructor with a `modes` parameter value of is equivalent to calling the constructor with an `isJITTrackingEnabled` parameter value of `true`. + Calling the constructor with a `modes` parameter value of is equivalent to calling the constructor with an `isJITTrackingEnabled` parameter value of `true`. ]]> @@ -188,7 +188,7 @@ and . + This constructor sets the properties and . An `isJITTrackingEnabled` parameter value of `true` causes the runtime to track information important to the debugger during code generation; a value of `false` results in no tracking, but does not prevent debugging. This parameter has no effect in the .NET Framework version 2.0. In version 2.0, JIT tracking information, the Microsoft intermediate language (MSIL) offset to the native-code offset within a method, is always generated. @@ -290,7 +290,7 @@ is set to `false`, stepping through code might result in a different behavior than when set to `true` because the compiler might reorder instructions or insert jumps to common code. + A value of `true` enhances performance for runtime debugging, which can cause a decline in execution performance. A value of `false` enhances performance for execution. When is set to `false`, stepping through code might result in a different behavior than when set to `true` because the compiler might reorder instructions or insert jumps to common code. ]]> @@ -340,7 +340,7 @@ controls whether the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. + controls whether the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. Starting in .NET Framework 2.0, JIT tracking information is always enabled during debugging, and this property value is ignored. diff --git a/xml/System.Diagnostics/Debugger.xml b/xml/System.Diagnostics/Debugger.xml index a364a85aefd..62e3c3c3ff3 100644 --- a/xml/System.Diagnostics/Debugger.xml +++ b/xml/System.Diagnostics/Debugger.xml @@ -166,12 +166,12 @@ If no debugger is attached, users are asked if they want to attach a debugger. If users say yes, the debugger is started. If a debugger is attached, the debugger is signaled with a user breakpoint event, and the debugger suspends execution of the process just as if a debugger breakpoint had been hit. > [!WARNING] -> Starting with .NET Framework 4, the runtime no longer exercises tight control of launching the debugger for the method, but instead reports an error to the Windows Error Reporting (WER) subsystem. WER provides many settings to customize the problem reporting experience, so a lot of factors will influence the way WER responds to an error such as operating system version, process, session, user, machine and domain. If you're having unexpected results when calling the method, check the WER settings on your machine. For more information on how to customize WER, see [WER Settings](/windows/win32/wer/wer-settings). If you want to ensure the debugger is launched regardless of the WER settings, be sure to call the method instead. +> Starting with .NET Framework 4, the runtime no longer exercises tight control of launching the debugger for the method, but instead reports an error to the Windows Error Reporting (WER) subsystem. WER provides many settings to customize the problem reporting experience, so a lot of factors will influence the way WER responds to an error such as operating system version, process, session, user, machine and domain. If you're having unexpected results when calling the method, check the WER settings on your machine. For more information on how to customize WER, see [WER Settings](/windows/win32/wer/wer-settings). If you want to ensure the debugger is launched regardless of the WER settings, be sure to call the method instead. ## Examples - The following code example demonstrates how to stop the debugger at the call to . + The following code example demonstrates how to stop the debugger at the call to . ```vb Debugger.Break() @@ -277,7 +277,7 @@ Console.WriteLine("Hello, world."); is used by . + The value of this default constant is `null`. is used by . ]]> @@ -581,7 +581,7 @@ Debugger launch is only supported on Windows. On Unix operating systems, the met ## Remarks Debuggers must specifically enable callbacks that they wish to receive. A debugger that wants to receive cross-thread dependency callbacks must call the [ICorDebugProcess3::SetEnableCustomNotification](/dotnet/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method) method. - A debugger that has selected can take appropriate action upon notification. For example, performing a function evaluation typically requires freezing all threads except for the thread that is performing the evaluation. If the function evaluation requires execution on more than one thread, as might occur in remoting scenarios, the evaluation will block. The notification informs the debugger that it has to release a thread or abort the function evaluation. The notification is subject to collection after this method returns. + A debugger that has selected can take appropriate action upon notification. For example, performing a function evaluation typically requires freezing all threads except for the thread that is performing the evaluation. If the function evaluation requires execution on more than one thread, as might occur in remoting scenarios, the evaluation will block. The notification informs the debugger that it has to release a thread or abort the function evaluation. The notification is subject to collection after this method returns. ]]> diff --git a/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml b/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml index 9c0af9636f6..33dd23f37b1 100644 --- a/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml +++ b/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml @@ -146,7 +146,7 @@ ## Examples The following code example shows the use of a attribute to instruct the debugger to not display the root (property name) of the `Keys` property, but to display the elements of the array that `Keys` gets. This code example is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/program.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/module1.vb" id="Snippet6"::: @@ -203,7 +203,7 @@ constructor uses the value of the `state` parameter to set this value. + The constructor uses the value of the `state` parameter to set this value. ]]> diff --git a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml index 2243c85a46d..4eca7195caf 100644 --- a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml +++ b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml @@ -75,7 +75,7 @@ constructor has a single argument: a string to be displayed in the value column for instances of the type. This string can contain braces ({ and }). The text within a pair of braces is evaluated as the name of a field, property, or method. For example, the following C# code causes "Count = 4" to be displayed when the plus sign (+) is selected to expand the debugger display for an instance of `MyHashtable`. + The constructor has a single argument: a string to be displayed in the value column for instances of the type. This string can contain braces ({ and }). The text within a pair of braces is evaluated as the name of a field, property, or method. For example, the following C# code causes "Count = 4" to be displayed when the plus sign (+) is selected to expand the debugger display for an instance of `MyHashtable`. ```csharp [DebuggerDisplay("Count = {count}")] diff --git a/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml b/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml index c01e3f636fb..d602b6eddee 100644 --- a/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml +++ b/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml @@ -226,7 +226,7 @@ ## Examples - The following code example shows the use of the constructor to specify a debugger display proxy. This code example is part of a larger example provided for the class. + The following code example shows the use of the constructor to specify a debugger display proxy. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/module1.vb" id="Snippet5"::: diff --git a/xml/System.Diagnostics/DefaultTraceListener.xml b/xml/System.Diagnostics/DefaultTraceListener.xml index 3edc546b676..9c4c825ff51 100644 --- a/xml/System.Diagnostics/DefaultTraceListener.xml +++ b/xml/System.Diagnostics/DefaultTraceListener.xml @@ -60,14 +60,14 @@ and collections. Explicitly adding a second causes duplicate messages in the debugger output window and duplicate message boxes for asserts. + An instance of this class is automatically added to the and collections. Explicitly adding a second causes duplicate messages in the debugger output window and duplicate message boxes for asserts. - By default, the and methods emit the message to the Win32 [OutputDebugString](/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw) function and to the method. + By default, the and methods emit the message to the Win32 [OutputDebugString](/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw) function and to the method. - The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . + The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . > [!NOTE] -> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -91,11 +91,11 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ``` ## Examples - The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. - If an error is detected while processing the input parameter, or if the `CalcBinomial` function throws an exception, the method logs and displays an error message. If the property is `false`, the error message is also written to the console. When the result is calculated successfully, the and methods write the results to the log file. + If an error is detected while processing the input parameter, or if the `CalcBinomial` function throws an exception, the method logs and displays an error message. If the property is `false`, the error message is also written to the console. When the result is calculated successfully, the and methods write the results to the log file. - The , , and methods cause trace information to be written only to the . To write trace information to all listeners in the collection, use the , , and methods of the class. + The , , and methods cause trace information to be written only to the . To write trace information to all listeners in the collection, use the , , and methods of the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet11"::: @@ -150,7 +150,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati provided by the application from the collection and then creates a new and adds it to the collection. + The following code example removes the provided by the application from the collection and then creates a new and adds it to the collection. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet3"::: @@ -209,7 +209,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati method to log an error message if the function throws an exception. If the property is `false`, the method also writes the error message to the console. + The following code example calls a function that calls the method to log an error message if the function throws an exception. If the property is `false`, the method also writes the error message to the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet8"::: @@ -281,7 +281,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ## Examples - The following code example writes an error message to a using the method. The method also writes the message to the console if a user interface is not available. + The following code example writes an error message to a using the method. The method also writes the message to the console if a user interface is not available. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet6"::: @@ -351,7 +351,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ## Examples - The following code example calls a function that calls the method to log a detailed error message if the function throws an exception. The method writes the message to the console if a user interface is not available. + The following code example calls a function that calls the method to log a detailed error message if the function throws an exception. The method writes the message to the console if a user interface is not available. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet8"::: @@ -410,7 +410,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet4"::: @@ -478,7 +478,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ## Examples - The following code example formats the results of a function and uses the method to write the first part of the message to a . + The following code example formats the results of a function and uses the method to write the first part of the message to a . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Write/defaulttracelistener.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Write/defaulttracelistener.vb" id="Snippet4"::: @@ -556,7 +556,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ## Examples - The following code example formats the results of a function and uses the method to write the last part of the message to a . + The following code example formats the results of a function and uses the method to write the last part of the message to a . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Write/defaulttracelistener.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Write/defaulttracelistener.vb" id="Snippet4"::: diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 1a7798edb93..5a44c4f9292 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -58,12 +58,12 @@ The trace output is in a delimited text format that uses the delimiter specified by the property. The delimiter is used to terminate each field in a line of output. For example, to display the trace output in a Microsoft Excel spreadsheet, you might specify a comma (",") as a delimiter and create a comma-separated value (CSV) file. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. You can create a in your code. Alternatively, in .NET Framework apps only, you can enable or disable a through the application configuration file and then use the configured in your application. > [!NOTE] -> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. +> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. To configure a in a .NET Framework app, edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: @@ -431,7 +431,7 @@ To configure a in a .NET Fr class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + This constructor initializes a new instance of the class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. @@ -669,7 +669,7 @@ The following .NET Framework application configuration file example shows the us The values of the `source`, `eventType`, and `id` parameters are written as a header. The data object is converted to a string using the `ToString` method of the object. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -747,7 +747,7 @@ The following .NET Framework application configuration file example shows the us The values of the `source`, `eventType`, and `id` parameters are written as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -828,7 +828,7 @@ The following .NET Framework application configuration file example shows the us The values of the `source`, `eventType`, and `id` parameters are written as a header, followed by the `message` data. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> @@ -913,10 +913,10 @@ The following .NET Framework application configuration file example shows the us method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. + The values of the `source`, `eventType`, and `id` parameters are written as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. ]]> diff --git a/xml/System.Diagnostics/DiagnosticListener.xml b/xml/System.Diagnostics/DiagnosticListener.xml index 2313d477a93..855af64ea17 100644 --- a/xml/System.Diagnostics/DiagnosticListener.xml +++ b/xml/System.Diagnostics/DiagnosticListener.xml @@ -48,7 +48,7 @@ ## Remarks -`DiagnosticListener` is a NotificationSource, which means the returned result can be used to log notifications, but it also has a method so notifications can be forwarded arbitrarily. Thus, its job is to forward things from the producer to all the listeners (multi-casting). Generally, you should not be making your own but use the default, so that notifications are as public as possible. +`DiagnosticListener` is a NotificationSource, which means the returned result can be used to log notifications, but it also has a method so notifications can be forwarded arbitrarily. Thus, its job is to forward things from the producer to all the listeners (multi-casting). Generally, you should not be making your own but use the default, so that notifications are as public as possible. For more information on the and classes, see [DiagnosticSource User's Guide](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md). @@ -520,15 +520,15 @@ If setup for the notification is expensive, you can call `IsEnabled()` before pe If `isEnabled` is not `null`, it indicates that some events are uninteresting can be skipped for efficiency. -A particular instrumentation site has the option of calling one or more overloads in which it passes the name of the event and up to two other (instrumentation site specific) objects as arguments. If any of these calls are made then this `isEnabled` predicate is invoked with passed values (if shorter overloads are used, `null` is passed for missing context objects). +A particular instrumentation site has the option of calling one or more overloads in which it passes the name of the event and up to two other (instrumentation site specific) objects as arguments. If any of these calls are made then this `isEnabled` predicate is invoked with passed values (if shorter overloads are used, `null` is passed for missing context objects). This gives any particular instrumentation site the ability to pass up to two pieces of information to the subscriber to do sophisticated, efficient filtering. This requires more coupling between the instrumentation site and the subscriber code. It is expected that a particular instrumentation site may call different overloads of `IsEnabled` for the same event, first calling , which calls the filter with two `null` context objects. If `isEnabled` returns `true`, it calls again with context objects. The `isEnabled` filter should be designed with this in mind. -Note that the `isEnabled` predicate is an optional optimization to allow the instrumentation site to avoid setting up the payload and calling when no subscriber cares about it. In particular, the instrumentation site has the option of ignoring the predicate (not calling it) and simply calling . Thus, if the subscriber requires the filtering, it needs to do it itself. +Note that the `isEnabled` predicate is an optional optimization to allow the instrumentation site to avoid setting up the payload and calling when no subscriber cares about it. In particular, the instrumentation site has the option of ignoring the predicate (not calling it) and simply calling . Thus, if the subscriber requires the filtering, it needs to do it itself. -If this parameter is `null`, no filtering is done (all overloads of return `true`). +If this parameter is `null`, no filtering is done (all overloads of return `true`). ]]> @@ -590,7 +590,7 @@ If this parameter is `null`, no filtering is done (all overloads of when no subscriber cares about it. In particular the instrumentation site has the option of ignoring the predicate (not calling it) and simply calling . Thus if the subscriber requires the filtering, it needs to do it itself. -If `isEnabled` is `null`, no filtering is done (all overloads of return `true`). +If `isEnabled` is `null`, no filtering is done (all overloads of return `true`). ]]> @@ -661,9 +661,9 @@ If `isEnabled` is `null`, no filtering is done (all overloads of Adds a subscriber, optionally filters events based on their name and up to two context objects, and specifies methods to call when providers import or export activites from outside the process. A reference to an interface that allows the listener to stop receiving notifications before the has finished sending them. - An object that represents the payload for the event. Logs a notification. - method. +For more information, see the method. ]]> diff --git a/xml/System.Diagnostics/DiagnosticsConfigurationHandler.xml b/xml/System.Diagnostics/DiagnosticsConfigurationHandler.xml index a603d1c06a4..48681507415 100644 --- a/xml/System.Diagnostics/DiagnosticsConfigurationHandler.xml +++ b/xml/System.Diagnostics/DiagnosticsConfigurationHandler.xml @@ -28,11 +28,11 @@ Handles the diagnostics section of configuration files. - method is a section handler that participates in the resolution of configuration settings in the [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element) portion of configuration files. - + method is a section handler that participates in the resolution of configuration settings in the [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element) portion of configuration files. + ]]> @@ -96,25 +96,25 @@ Parses the configuration settings for the <system.diagnostics> Element section of configuration files. A new configuration object, in the form of a . - method populates a with the values obtained from the [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element) section of a configuration file and returns the hash table. - + method populates a with the values obtained from the [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element) section of a configuration file and returns the hash table. + ]]> - Switches could not be found. - - -or- - - Assert could not be found. - - -or- - - Trace could not be found. - - -or- - + Switches could not be found. + + -or- + + Assert could not be found. + + -or- + + Trace could not be found. + + -or- + Performance counters could not be found. diff --git a/xml/System.Diagnostics/EntryWrittenEventArgs.xml b/xml/System.Diagnostics/EntryWrittenEventArgs.xml index efb8b38f332..de259695ed6 100644 --- a/xml/System.Diagnostics/EntryWrittenEventArgs.xml +++ b/xml/System.Diagnostics/EntryWrittenEventArgs.xml @@ -37,8 +37,8 @@ constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. - + The following example demonstrates the constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EntryWrittenEventArgs/Overview/entrywritteneventargs_ctor1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EntryWrittenEventArgs/Overview/entrywritteneventargs_ctor1.vb" id="Snippet1"::: @@ -96,7 +96,7 @@ constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. + The following example demonstrates the constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EntryWrittenEventArgs/Overview/entrywritteneventargs_ctor1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EntryWrittenEventArgs/Overview/entrywritteneventargs_ctor1.vb" id="Snippet1"::: @@ -147,7 +147,7 @@ constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. + The following example demonstrates the constructor. It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom . This object is used to notify a message. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EntryWrittenEventArgs/.ctor/entrywritteneventargs_ctor2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EntryWrittenEventArgs/.ctor/entrywritteneventargs_ctor2.vb" id="Snippet1"::: @@ -198,7 +198,7 @@ . + The following example assumes that you have already implemented the sample in . It creates a custom object and writes an entry into it. Then it creates an object using the first entry in the custom EventLog. This object is used to notify a message. diff --git a/xml/System.Diagnostics/EventInstance.xml b/xml/System.Diagnostics/EventInstance.xml index c75fc76c96a..2a63fdd8701 100644 --- a/xml/System.Diagnostics/EventInstance.xml +++ b/xml/System.Diagnostics/EventInstance.xml @@ -36,17 +36,17 @@ to write an event log entry with a resource identifier rather than a string value. To write an event log entry, initialize the property and pass the instance to the method. The Event Viewer uses the instance identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the event source with the corresponding resource file before you write events using resource identifiers. + Use to write an event log entry with a resource identifier rather than a string value. To write an event log entry, initialize the property and pass the instance to the method. The Event Viewer uses the instance identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the event source with the corresponding resource file before you write events using resource identifiers. When writing events, you can set the property to specify the icon that the Event Viewer displays for the entry. You can also specify a property to specify the category that the Event Viewer displays for the entry. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified does not index a string in the category resource file, and then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified does not index a string in the category resource file, and then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. - You must register a source for an event log before using to write an event with the method. The source must be configured for writing localized entries to the log and the source must define at least a message resource file. + You must register a source for an event log before using to write an event with the method. The source must be configured for writing localized entries to the log and the source must define at least a message resource file. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. For details about defining event messages and building event log resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -223,7 +223,7 @@ SVC_UPDATE.EXE and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The property for the new instance is set to by default. + To write an informational entry to an event log, initialize an and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The property for the new instance is set to by default. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource files for the source. You must register the source with the corresponding resource files before you can write events using resource identifiers. @@ -400,7 +400,7 @@ SVC_UPDATE.EXE and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. + To write an entry to an event log, initialize an and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource files for the source. You must register the source with the corresponding resource files before you can write events using resource identifiers. @@ -587,13 +587,13 @@ SVC_UPDATE.EXE ## Remarks Event log categories are application-defined values that help filter events, or provide further information about the event. For example, your application can define separate categories for different components or different operations. - Set the property to specify the category that the Event Viewer displays for the entry. The Event Viewer can display the category as a numeric value, or it can use the as a resource identifier to display a localized category string based on the current language settings. + Set the property to specify the category that the Event Viewer displays for the entry. The Event Viewer can display the category as a numeric value, or it can use the as a resource identifier to display a localized category string based on the current language settings. - To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified does not index a string in the category resource file, and then the Event Viewer displays the numeric category value for that entry. + To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified does not index a string in the category resource file, and then the Event Viewer displays the numeric category value for that entry. You must register the source with the corresponding resource file before you write event categories using resource identifiers. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. When defining category strings in a resource file, the category resource identifiers must be numbered consecutively starting at 1, up to the configured property value. - Event categories are optional. If your application does not use categories, do not set the for the event log entry. + Event categories are optional. If your application does not use categories, do not set the for the event log entry. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. For details about defining event categories in resource files, see the "Event Categories" topic in the Platform SDK @@ -940,7 +940,7 @@ SVC_UPDATE.EXE property uniquely identifies an event entry for a configured event source. For events defined in message resource files, the corresponds to the resource identifier compiled from the message definition fields in the message text file. Your application can write localized event log entries by setting the to a resource identifier. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the source with the corresponding resource file before you write events using resource identifiers. + The property uniquely identifies an event entry for a configured event source. For events defined in message resource files, the corresponds to the resource identifier compiled from the message definition fields in the message text file. Your application can write localized event log entries by setting the to a resource identifier. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the source with the corresponding resource file before you write events using resource identifiers. For details about defining event messages and building event log resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. For details about event log identifiers, see the [Event Identifiers](/windows/win32/eventlog/event-categories) article in the Platform SDK documentation. diff --git a/xml/System.Diagnostics/EventLog.xml b/xml/System.Diagnostics/EventLog.xml index 07a38def534..cae94fbca86 100644 --- a/xml/System.Diagnostics/EventLog.xml +++ b/xml/System.Diagnostics/EventLog.xml @@ -70,7 +70,7 @@ lets you access or customize Windows event logs, which record information about important software or hardware events. Using , you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and respond to log entries. You can also create new logs when creating an event source. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. In addition to providing access to individual event logs and their entries, the class lets you access the collection of all event logs. You can use the `static` members of to delete logs, get log lists, create or delete a source, or determine if a computer already contains a particular source. @@ -80,11 +80,11 @@ Starting with Windows Vista, User Account Control (UAC) determines the credentials of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To run the code that accesses the Security log, you must first elevate your credentials from standard user to administrator. You can do this when you start an application by opening the shortcut menu for the application (if you're using a mouse, right-click the application icon) and indicating that you want to run as an administrator. - You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. + You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. To read from an event log, specify the log name ( property) and server computer name ( property for the event log. If you don't specify the server computer name, the local computer, ".", is assumed. It's not necessary to specify the event source ( property), because a source is required only for writing to logs. The property is automatically populated with the event log's list of entries. - To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. + To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. If the event source for the event log associated with the instance doesn't exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative credentials. @@ -98,15 +98,15 @@ > [!NOTE] > There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. - Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system hasn't refreshed its list of event sources, and you try to write an event with the new source, the write operation will fail. You can configure a new source by using an object or the method. You must have administrative credentials on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system hasn't refreshed its list of event sources, and you try to write an event with the new source, the write operation will fail. You can configure a new source by using an object or the method. You must have administrative credentials on the computer to create a new event source. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration instead of deleting the existing source. You can register the event source with localized resources for your event category and message strings. Your application can write event log entries by using resource identifiers instead of specifying the actual string values. Refer to the and classes for more information about configuring your source with resource files. - If your application writes string values directly to the event log, you do not have to set the resource file properties for the source. The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes string values directly to the event log, you do not have to set the resource file properties for the source. The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. When writing events, you must at least specify either a message string or the resource identifier for a message string. Other event properties are optional. Examples of optional event settings include the following: @@ -119,7 +119,7 @@ > [!IMPORTANT] > Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. We recommend that you place event log calls in an error path, rather than in the main code path, so they don't adversely affect performance. - For a list of initial property values for an instance of , see the constructor. + For a list of initial property values for an instance of , see the constructor. @@ -187,18 +187,18 @@ , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. +> If you do not specify a , the local computer (".") is assumed. The following table shows initial property values for an instance of . |Property|Initial Value| |--------------|-------------------| -||An empty string ("").| -||An empty string ("").| -||The local computer (".").| +||An empty string ("").| +||An empty string ("").| +||The local computer (".").| @@ -261,20 +261,20 @@ property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + This overload sets the property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. +> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. - If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. + If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. The following table shows initial property values for an instance of . |Property|Initial Value| |--------------|-------------------| -||An empty string ("").| -||The `logName` parameter.| -||The local computer (".").| +||An empty string ("").| +||The `logName` parameter.| +||The local computer (".").| @@ -341,18 +341,18 @@ property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. + This overload sets the property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> This overload of the constructor specifies the and properties, but you can change either before reading the property. +> This overload of the constructor specifies the and properties, but you can change either before reading the property. The following table shows initial property values for an instance of . |Property|Initial Value| |--------------|-------------------| -||An empty string ("").| -||The `logName` parameter.| -||The `machineName` parameter.| +||An empty string ("").| +||The `logName` parameter.| +||The `machineName` parameter.| @@ -419,15 +419,15 @@ property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. + This constructor sets the property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. The following table shows initial property values for an instance of . |Property|Initial Value| |--------------|-------------------| -||The `source` parameter.| -||The `logName` parameter.| -||The `machineName` parameter.| +||The `source` parameter.| +||The `logName` parameter.| +||The `machineName` parameter.| @@ -493,7 +493,7 @@ method ends the initialization. Using the and methods prevent the control from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to start the initialization of a component used on a form or by another component. The method ends the initialization. Using the and methods prevent the control from being used before it is fully initialized. ]]> @@ -540,7 +540,7 @@ ## Remarks Event logs are set with a maximum size that determines how many entries they can contain. When an event log is full, it stops recording new event information or begins to overwrite earlier entries. If event recording stops, you can use this method to clear the log of existing entries and allow it to start recording events again. You must have administrator permissions to the computer on which the log resides to clear event log entries. - closes the event log, releases the event handles, retrieves new read and write handles, and reopens the event log. Events received after the call to the method are not cleared along with the existing events. + closes the event log, releases the event handles, retrieves new read and write handles, and reopens the event log. Events received after the call to the method are not cleared along with the existing events. @@ -602,7 +602,7 @@ method is called by the protected method. You do not need to invoke before calling . + The method is called by the protected method. You do not need to invoke before calling . ]]> @@ -660,7 +660,7 @@ ## Remarks Use this overload to configure a new source for writing entries to an event log on the local computer or a remote computer. It is not necessary to use this method to read from an event log. - The method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. + The method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. > [!NOTE] > To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. @@ -669,19 +669,19 @@ > > Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. Each source can only write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - You can register the event source with localized resource file(s) for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. + You can register the event source with localized resource file(s) for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. @@ -895,9 +895,9 @@ SVC_UPDATE.EXE to an existing log on the local computer. + Use this overload to create a custom log or to create and register a to an existing log on the local computer. - If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the local computer, the system creates a custom log and registers your application as a for that log. + If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the local computer, the system creates a custom log and registers your application as a for that log. > [!NOTE] > To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. @@ -906,22 +906,22 @@ SVC_UPDATE.EXE > > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. @@ -1033,11 +1033,11 @@ SVC_UPDATE.EXE to an existing log on the specified computer. + Use this overload to create a custom log or to create and register a to an existing log on the specified computer. - If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the specified computer, the system creates a custom log and registers your application as a for that log. + If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the specified computer, the system creates a custom log and registers your application as a for that log. - You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] > To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. @@ -1046,17 +1046,17 @@ SVC_UPDATE.EXE > > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. @@ -1163,14 +1163,14 @@ SVC_UPDATE.EXE ## Remarks Use this method when the log you want to delete is on the local computer. You can delete any log on the computer, provided you have the appropriate registry permissions. - removes the log specified by `logName` from the local computer. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create a new instance of to call either method. + removes the log specified by `logName` from the local computer. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create a new instance of to call either method. - The method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. + The method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. > [!NOTE] > Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. @@ -1246,14 +1246,14 @@ SVC_UPDATE.EXE ## Remarks Use this method when the log you want to delete is on a remote computer. You can delete any log on the computer, provided you have the appropriate registry permissions. - removes the log specified by `logName` from the computer specified by `machineName`. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + removes the log specified by `logName` from the computer specified by `machineName`. If you want to delete only the source registered to a log, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. This method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. > [!NOTE] > Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. @@ -1345,13 +1345,13 @@ SVC_UPDATE.EXE from the local computer. accesses the registry on the local computer and removes the registration of your application as a valid source of events. + Use this method to remove the registration of a from the local computer. accesses the registry on the local computer and removes the registration of your application as a valid source of events. You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. - removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. > [!NOTE] > If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -1422,13 +1422,13 @@ SVC_UPDATE.EXE from a remote computer. accesses the registry on the computer specified by `machineName` and removes the registration of your application as a valid source of events. + Use this overload to remove the registration of a from a remote computer. accesses the registry on the computer specified by `machineName` and removes the registration of your application as a valid source of events. You can remove your component as a valid source of events if you no longer need it to write entries to that log. For example, you might do this if you need to change your component from one log to another. Because a source can only be registered to one log at a time, changing the log requires you to remove the current registration. - removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. + removes only the source registered to a log. If you want to remove the log itself, call . If you only want to delete the log entries, call . and are `static` methods, so they can be called on the class itself. It is not necessary to create an instance of to call either method. - Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. + Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. > [!NOTE] > If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -1570,7 +1570,7 @@ SVC_UPDATE.EXE property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. + The property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. > [!NOTE] > You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. @@ -1628,7 +1628,7 @@ SVC_UPDATE.EXE method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to end the initialization of a component used on a form or by another component. The method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -1685,16 +1685,16 @@ SVC_UPDATE.EXE member when reading from the event log. + Use the member when reading from the event log. - Because the property is read-only, you cannot modify an entry or write to the log using . Instead, specify a and call to write a new log entry. You can use to count the number of entries in the event log, and view each in the collection. Use the indexed member to retrieve information about a specific entry, such as , , , or . + Because the property is read-only, you cannot modify an entry or write to the log using . Instead, specify a and call to write a new log entry. You can use to count the number of entries in the event log, and view each in the collection. Use the indexed member to retrieve information about a specific entry, such as , , , or . - It is not necessary to specify a when only reading from a log. You can specify only the name and (server computer name) properties for the instance. In either case, the member is automatically populated with the event log's list of entries. You can select the appropriate index for an item in this list to read individual entries. + It is not necessary to specify a when only reading from a log. You can specify only the name and (server computer name) properties for the instance. In either case, the member is automatically populated with the event log's list of entries. You can select the appropriate index for an item in this list to read individual entries. - An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. + An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. @@ -1755,11 +1755,11 @@ SVC_UPDATE.EXE to `true`. You can only receive event notifications when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. + To get event notifications, you must set to `true`. You can only receive event notifications when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, until you remove the delegate. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). - The system responds to only if the last write event occurred at least six seconds previously. This implies you will only receive one event notification within a six-second interval, even if more than one event log change occurs. If you insert a sufficiently long sleep interval (around 10 seconds) between calls to , you are less likely to miss an event. However, if write events occur more frequently, you might not receive the event notification until the next interval. Typically, missed event notifications are not lost, but delayed. + The system responds to only if the last write event occurred at least six seconds previously. This implies you will only receive one event notification within a six-second interval, even if more than one event log change occurs. If you insert a sufficiently long sleep interval (around 10 seconds) between calls to , you are less likely to miss an event. However, if write events occur more frequently, you might not receive the event notification until the next interval. Typically, missed event notifications are not lost, but delayed. @@ -1830,13 +1830,13 @@ SVC_UPDATE.EXE . + Use this method to determine if a log exists on the local computer. If you want to determine whether a source exists on the local computer, use . Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, the query returns `false`. Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if the specified `logName` already exists on the local computer. The `logName` parameter is not case sensitive. - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . @@ -1896,13 +1896,13 @@ SVC_UPDATE.EXE . + Use this method to determine if a log exists on a remote computer. If you want to determine whether a source exists on a remote computer, use . Because this method accesses the registry, you must have the appropriate registry permissions on the specified computer; otherwise, the query returns `false`. Because you cannot give a new log the name of an existing log on the same computer, use this method before creating a new log to determine if one with the specified `logName` already exists on the server specified by the `machineName` parameter. The `logName` and `machineName` parameters are not case sensitive. - is a `static` method, so it can be called on the class itself. It is not necessary to create a new instance of to call . + is a `static` method, so it can be called on the class itself. It is not necessary to create a new instance of to call . ]]> @@ -1970,9 +1970,9 @@ SVC_UPDATE.EXE objects is a snapshot of all event logs on the local computer when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the local computer, they will appear in the array as well. + The array of objects is a snapshot of all event logs on the local computer when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the local computer, they will appear in the array as well. - To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . + To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . ## Examples The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. @@ -2031,11 +2031,11 @@ SVC_UPDATE.EXE objects is a snapshot of all event logs on the computer specified by the `machineName` parameter when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the specified computer, they will appear in the array as well. + The array of objects is a snapshot of all event logs on the computer specified by the `machineName` parameter when the call to is made. This is not a dynamic collection, so it does not reflect the deletion or creation of logs in real time. You should verify that a log in the array exists before you read or write to it. The array usually includes at least three logs: Application, System, and Security. If you created custom logs on the specified computer, they will appear in the array as well. - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of an object to make a call to the method. + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of an object to make a call to the method. - To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . + To retrieve the list of event logs, you must have the appropriate registry permissions. These permissions are identical to those required to call and . @@ -2133,20 +2133,20 @@ SVC_UPDATE.EXE > [!NOTE] > Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. - If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. + If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. + If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. + You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. - If the value changes, the event log is closed and all event handles are released. + If the value changes, the event log is closed and all event handles are released. > [!CAUTION] > If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. @@ -2221,7 +2221,7 @@ SVC_UPDATE.EXE ## Examples - The following example enumerates the event logs defined on the local computer and displays the for each event log. + The following example enumerates the event logs defined on the local computer and displays the for each event log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/GetEventLogs/source1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/GetEventLogs/source1.vb" id="Snippet2"::: @@ -2276,7 +2276,7 @@ SVC_UPDATE.EXE ## Remarks The event source indicates what logs the event. It is often the name of the application, or the name of a subcomponent of the application, if the application is large. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. - When you create a new source, which can only write to one log at a time, the system registers your application with the event log as a valid source of entries. The property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. + When you create a new source, which can only write to one log at a time, the system registers your application with the event log as a valid source of entries. The property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. @@ -2355,14 +2355,14 @@ SVC_UPDATE.EXE with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). + If you write to an event log, you must associate a with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). > [!NOTE] -> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. +> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. - The value cannot be an empty string. If it is not explicitly set, it defaults to the local computer ("."). + The value cannot be an empty string. If it is not explicitly set, it defaults to the local computer ("."). @@ -2434,7 +2434,7 @@ SVC_UPDATE.EXE property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. + The property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. > [!NOTE] > This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. @@ -2572,7 +2572,7 @@ SVC_UPDATE.EXE > [!NOTE] > The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. - The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. + The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. > [!NOTE] > This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. @@ -2657,7 +2657,7 @@ SVC_UPDATE.EXE ## Remarks Event logs grow in size as new events are written to them. Each event log has a configured maximum size limit; the property defines the maximum number of kilobytes allowed for the event log file size. - Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. + Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. > [!NOTE] > The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. @@ -2724,11 +2724,11 @@ SVC_UPDATE.EXE to register and display a localized name in the Event Viewer for custom event logs. + Use to register and display a localized name in the Event Viewer for custom event logs. The specified resource identifier must correspond to a localized string defined in the resource file. The Event Viewer displays the custom event log name using the localized string and the current culture settings. For example, you can define multiple event log names localized for different cultures in your resource file. The Event Viewer displays the localized string corresponding to the culture settings of the current user. - If the Event Viewer cannot load the localized string from the resource file, or if no display name was registered for the event log, then the Event Viewer displays the event log name defined in . + If the Event Viewer cannot load the localized string from the resource file, or if no display name was registered for the event log, then the Event Viewer displays the event log name defined in . > [!NOTE] > You do not need to register a display name for the pre-defined event logs. The operating system registers the localized display names for the Application, System, and Security event logs. @@ -2938,22 +2938,22 @@ SVC_UPDATE.EXE ## Remarks The event source indicates what logs the event. It is often the name of the application, or the name of a subcomponent of the application, if the application is large. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. - You only need to specify an event source if you are writing to an event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + You only need to specify an event source if you are writing to an event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. - Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - If you change the value, the to which it is registered is closed and all event handles are released. + If you change the value, the to which it is registered is closed and all event handles are released. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. @@ -3034,7 +3034,7 @@ SVC_UPDATE.EXE . + Use this method to determine whether an event source exists on the local computer. If you want to determine whether a log exists on the local computer, use . Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, a will be thrown. @@ -3048,7 +3048,7 @@ SVC_UPDATE.EXE > [!NOTE] > A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. - Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the local computer. The `source` parameter is not case-sensitive. + Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the local computer. The `source` parameter is not case-sensitive. @@ -3117,7 +3117,7 @@ SVC_UPDATE.EXE . + Use this method to determine whether an event source exists on the computer specified by the `machineName` parameter. If you want to determine whether a log exists on the specified computer, use . Because this method accesses the registry, you must have the appropriate registry permissions on the given server; otherwise, a will be thrown. @@ -3131,9 +3131,9 @@ SVC_UPDATE.EXE > [!NOTE] > A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. - Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the computer. The `source` and `machineName` parameters are not case sensitive. + Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the computer. The `source` and `machineName` parameters are not case sensitive. - is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . + is a `static` method, so it can be called on the class itself. It is not necessary to create an instance of to call . @@ -3206,11 +3206,11 @@ SVC_UPDATE.EXE is `null`, methods handling the event are called on a thread from the system thread pool. For more information on system thread pools, see . + When is `null`, methods handling the event are called on a thread from the system thread pool. For more information on system thread pools, see . - When the event is handled by a visual Windows Forms component, such as a button, accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. + When the event is handled by a visual Windows Forms component, such as a button, accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. - If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. + If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. ]]> @@ -3272,28 +3272,28 @@ SVC_UPDATE.EXE instance. If you want to specify any other , use a different overload of . + Use this method to write an information entry to the event log associated with this instance. If you want to specify any other , use a different overload of . > [!NOTE] > The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many of the exceptions listed above are generated by errors raised during the process of registering the . +> Many of the exceptions listed above are generated by errors raised during the process of registering the . - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. @@ -3391,21 +3391,21 @@ SVC_UPDATE.EXE You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. @@ -3498,13 +3498,13 @@ SVC_UPDATE.EXE ## Remarks - Use this method to write an information entry to the event log, using a source that is already registered as an event source for the appropriate log. If you want to specify any other , use a different overload of . + Use this method to write an information entry to the event log, using a source that is already registered as an event source for the appropriate log. If you want to specify any other , use a different overload of . - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3599,21 +3599,21 @@ SVC_UPDATE.EXE You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. @@ -3716,11 +3716,11 @@ SVC_UPDATE.EXE > [!NOTE] > The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3827,21 +3827,21 @@ SVC_UPDATE.EXE You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. @@ -3946,13 +3946,13 @@ SVC_UPDATE.EXE > [!NOTE] > The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - In addition to the event identifier, this overload of lets you specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. + In addition to the event identifier, this overload of lets you specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -4059,21 +4059,21 @@ SVC_UPDATE.EXE You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. @@ -4186,11 +4186,11 @@ SVC_UPDATE.EXE Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -4296,11 +4296,11 @@ SVC_UPDATE.EXE Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -4411,17 +4411,17 @@ SVC_UPDATE.EXE ## Remarks - Use this method to write a localized entry to the event log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the . You must register the source with the corresponding resource file before you write events using resource identifiers. + Use this method to write a localized entry to the event log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the . You must register the source with the corresponding resource file before you write events using resource identifiers. - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running .NET. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. @@ -4637,22 +4637,22 @@ SVC_UPDATE.EXE . You must register the source with the corresponding resource file before you write events using resource identifiers. + Use this method to write a localized entry with additional event-specific data to the event log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the . You must register the source with the corresponding resource file before you write events using resource identifiers. - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. - You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. > [!NOTE] -> If you do not specify a for your instance before you call , the local computer (".") is assumed. +> If you do not specify a for your instance before you call , the local computer (".") is assumed. - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] > If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. @@ -4866,15 +4866,15 @@ SVC_UPDATE.EXE ## Remarks Use this method to write a localized entry to the event log, using a source already registered as an event source for the appropriate log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the source. You must register the source with the corresponding resource file before you write events using resource identifiers. - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. @@ -5083,17 +5083,17 @@ SVC_UPDATE.EXE ## Remarks Use this method to write a localized entry with additional event-specific data to the event log, using a source already registered as an event source for the appropriate log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the source. You must register the source with the corresponding resource file before you write events using resource identifiers. - The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. + The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. - The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + The specified source must be registered for an event log before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. - You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. + The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. diff --git a/xml/System.Diagnostics/EventLogEntry.xml b/xml/System.Diagnostics/EventLogEntry.xml index 10fd6aef37c..9ff46c6ceb6 100644 --- a/xml/System.Diagnostics/EventLogEntry.xml +++ b/xml/System.Diagnostics/EventLogEntry.xml @@ -56,10 +56,10 @@ directly when working with the class. The member of the class contains a collection of instances, which you iterate over when reading by using the class index member. + You usually will not create instances of directly when working with the class. The member of the class contains a collection of instances, which you iterate over when reading by using the class index member. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -273,7 +273,7 @@ ## Examples - The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, log entry source information is displayed at the console. + The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, log entry source information is displayed at the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.vb" id="Snippet1"::: @@ -385,9 +385,9 @@ property for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the event identifier. + This value represents the event identifier for the entry in the event log, with the top two bits masked off. The property for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the event identifier. - If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using or the Windows API `ReportEvent`, the property matches the resource identifier for the event, with the top two bits masked off. + If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using or the Windows API `ReportEvent`, the property matches the resource identifier for the event, with the top two bits masked off. ]]> @@ -487,9 +487,9 @@ property uniquely identifies an event entry for a configured event source. The for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. The property equals the with the top two bits masked off. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the resource identifier. + The property uniquely identifies an event entry for a configured event source. The for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. The property equals the with the top two bits masked off. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the resource identifier. - If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using , the property matches the resource identifier specified in the of the `instance` parameter. If the application wrote the event using the Windows API `ReportEvent`, the property matches the resource identifier specified in the `dwEventID` parameter. + If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using , the property matches the resource identifier specified in the of the `instance` parameter. If the application wrote the event using the Windows API `ReportEvent`, the property matches the resource identifier specified in the `dwEventID` parameter. For details about defining event messages and building event log resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. For details about event log identifiers, see the [Event Identifiers](/windows/win32/eventlog/event-categories) article in the Platform SDK documentation. @@ -655,7 +655,7 @@ ## Remarks This property retrieves only the replacement strings for the entry. To retrieve the full message, read the property. - The property contains the localized versions of replacement strings that are used in the event log entry. If you provide resource files that contain strings in each target language for your application, you can emit event log messages in the language that is used on that computer. To do that, create an instance of the class for the resource assembly that contains your replacement strings. The first parameter of the constructor identifies the resource assembly to be used. Use the method of that instance to supply localized messages for log events. The following code automatically sets the message to the language for the current culture. + The property contains the localized versions of replacement strings that are used in the event log entry. If you provide resource files that contain strings in each target language for your application, you can emit event log messages in the language that is used on that computer. To do that, create an instance of the class for the resource assembly that contains your replacement strings. The first parameter of the constructor identifies the resource assembly to be used. Use the method of that instance to supply localized messages for log events. The following code automatically sets the message to the language for the current culture. ```csharp ResourceManager LocRM = new ResourceManager("ReplacementStrings.TestStrings", @@ -719,7 +719,7 @@ e1.WriteEntry(LocRM.GetString("strMessage"), ## Examples - The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, the property information is displayed at the console. + The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, the property information is displayed at the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/EventLogEntryCollection.xml b/xml/System.Diagnostics/EventLogEntryCollection.xml index 48bdf4b9aa2..8c1579fd099 100644 --- a/xml/System.Diagnostics/EventLogEntryCollection.xml +++ b/xml/System.Diagnostics/EventLogEntryCollection.xml @@ -103,12 +103,12 @@ . An array of instances is fixed at the time it is instantiated. Therefore, you cannot read new entries by using the array that is returned by the method. + Because new entries are appended to the existing list, stepping through the collection enables you to access the entries that were created after you originally created the . An array of instances is fixed at the time it is instantiated. Therefore, you cannot read new entries by using the array that is returned by the method. ## Examples - The following example creates an array and uses the method to copy the contents of an into it. + The following example creates an array and uses the method to copy the contents of an into it. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntryCollection/Overview/eventlogentry_copyto.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntryCollection/Overview/eventlogentry_copyto.vb" id="Snippet2"::: @@ -212,7 +212,7 @@ method is a wrapper for the class that implements the enumerator. + The object that is returned by the method is a wrapper for the class that implements the enumerator. > [!NOTE] > If the collection is changed during the iteration, the iteration is terminated. To avoid this possibility, see the property for an alternative technique for iterating through a collection. @@ -324,7 +324,7 @@ method of the class to copy all or part of the collection to an array. + Use the method of the class to copy all or part of the collection to an array. ]]> @@ -369,7 +369,7 @@ class, the method always returns `false`. + For the class, the method always returns `false`. ]]> diff --git a/xml/System.Diagnostics/EventLogInstaller.xml b/xml/System.Diagnostics/EventLogInstaller.xml index 66300f5ccde..0b4858dd115 100644 --- a/xml/System.Diagnostics/EventLogInstaller.xml +++ b/xml/System.Diagnostics/EventLogInstaller.xml @@ -28,32 +28,32 @@ > [!NOTE] > The Security log is read-only. - The installer creates the event source that you specify in the property and registers it for the event log specified in property. This behavior is similar to calling on the component. + The installer creates the event source that you specify in the property and registers it for the event log specified in property. This behavior is similar to calling on the component. - Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. To install an event log, create a project installer class that inherits from , and set the for the class to `true`. Within your project, create an for each event log that your application will write to and add the instance to your project installer class. - When the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) is called, it looks at the . If it is `true`, the tool installs all the items in the collection that are associated with your project installer. If is `false`, the tool ignores the project installer. + When the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) is called, it looks at the . If it is `true`, the tool installs all the items in the collection that are associated with your project installer. If is `false`, the tool ignores the project installer. - You modify other properties of an either before or after adding the instance to the collection of your project installer, but before the installer tool runs. You must set the property if your application will be writing to the event log. + You modify other properties of an either before or after adding the instance to the collection of your project installer, but before the installer tool runs. You must set the property if your application will be writing to the event log. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. - You can register the event source with localized resource files for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. + You can register the event source with localized resource files for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Create a different source without resource files and then use that source in the method to write strings directly to the event log using that source. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Create a different source without resource files and then use that source in the method to write strings directly to the event log using that source. - Typically, you do not call the methods of the class from within your code; they are generally called only by Installutil.exe. The tool automatically calls the method during the installation process. It backs out failures, if necessary, by calling the method for the object that generated the exception. + Typically, you do not call the methods of the class from within your code; they are generally called only by Installutil.exe. The tool automatically calls the method during the installation process. It backs out failures, if necessary, by calling the method for the object that generated the exception. ## Examples - The following code example sets the installation properties for a new event source. The code example sets the source name and the event log name, and adds the to the collection. + The following code example sets the installation properties for a new event source. The code example sets the source name and the event log name, and adds the to the collection. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogInstaller/Overview/eventloginstaller.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogInstaller/Overview/eventloginstaller.vb" id="Snippet1"::: @@ -113,9 +113,9 @@ and properties to write events with localized category strings. The Event Viewer displays the category for an event entry, if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information on an event. For example, your application can define separate categories for different components or different operations. + Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry, if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information on an event. For example, your application can define separate categories for different components or different operations. - Event categories are optional; if your application does not use categories, do not set the and properties. + Event categories are optional; if your application does not use categories, do not set the and properties. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -292,9 +292,9 @@ SVC_UPDATE.EXE and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information about an event. For example, your application might have separate categories for different components or different operations. + Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information about an event. For example, your application might have separate categories for different components or different operations. - Event categories are optional; if your application does not use categories, do not set the and properties. + Event categories are optional; if your application does not use categories, do not set the and properties. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -455,9 +455,9 @@ SVC_UPDATE.EXE ## Remarks The component specified by the `component` parameter must be an ; otherwise, an exception is thrown. - Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). is used by Installutil.exe to set the property values for the to the values of an existing . + Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). is used by Installutil.exe to set the property values for the to the values of an existing . - If the of the that is passed in is an empty string (""), you must set the property to a valid value before the installer executes. + If the of the that is passed in is an empty string (""), you must set the property to a valid value before the installer executes. ]]> @@ -495,13 +495,13 @@ SVC_UPDATE.EXE method writes event log information to the registry, and associates the event log with a log that is specified by the property. If the log does not already exist (and a source is specified), creates a log and associates the new source with it. + The method writes event log information to the registry, and associates the event log with a log that is specified by the property. If the log does not already exist (and a source is specified), creates a log and associates the new source with it. - Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool automatically calls the method during the installation process to write registry information that is associated with the event log being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously-installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. + Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool automatically calls the method during the installation process to write registry information that is associated with the event log being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously-installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method skips registering the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method skips registering the source if the property matches a source name that is already registered for the same event log specified in the property. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -589,11 +589,11 @@ SVC_UPDATE.EXE To write entries to an event log, you must create a source and register it with an event log. An event source can only write to one log at a time. The installer uses the value of the property to register your application with the event log as a valid source of entries. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify a new source and an existing log, the installer creates a new event source and associates it with the log you specify. If you specify both a new source and a new log, the installer associates the new source with the new log in the registry, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. - For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. + For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. ]]> @@ -648,9 +648,9 @@ SVC_UPDATE.EXE ## Remarks Use the property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. - Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. + Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. - The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. + The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. @@ -827,7 +827,7 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer replaces the placeholders with the corresponding strings from the and formats the event log message for the localized event entry. + Use the property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer replaces the placeholders with the corresponding strings from the and formats the event log message for the localized event entry. For example, the following section of a message text file defines a string with a parameter placeholder: @@ -837,7 +837,7 @@ Severity = Success Facility = Application SymbolicName = COMPONENT_STARTING Language=English -Component %%6050 is starting. +Component %`50 is starting. . ``` @@ -853,9 +853,9 @@ TRIGGER.EXE . ``` - The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. + The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. - If your application writes event message strings directly to the event log, or if your does not contain messages with parameter insertion placeholders, do not set the property. + If your application writes event message strings directly to the event log, or if your does not contain messages with parameter insertion placeholders, do not set the property. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -1012,11 +1012,11 @@ SVC_UPDATE.EXE method undoes the effects of the method. is called if the installation of any component in the installation project fails. The method creates or sets the properties for an event log and event source. either deletes the event log and source or resets the properties of a pre-existing source to its pre-installation values. + The method undoes the effects of the method. is called if the installation of any component in the installation project fails. The method creates or sets the properties for an event log and event source. either deletes the event log and source or resets the properties of a pre-existing source to its pre-installation values. - Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool calls the method, when this or another component has failed to install, to undo any changes that the installation process has already made. + Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool calls the method, when this or another component has failed to install, to undo any changes that the installation process has already made. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -1067,11 +1067,11 @@ SVC_UPDATE.EXE The installer uses the value of the property to register your application with the event log as a valid source of entries. A new source name cannot match an existing source name or an existing event log name. Each source can only write to one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. - Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify the name of a log that does not exist, the system registers the to that log, but the log is not created until the first entry is written to it. + Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify the name of a log that does not exist, the system registers the to that log, but the log is not created until the first entry is written to it. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. - For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. + For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. ]]> @@ -1106,11 +1106,11 @@ SVC_UPDATE.EXE property value is `Remove`, the method deletes the source and the associated log that the installer created if the and properties specified the creation of a new event log and source. + If the property value is `Remove`, the method deletes the source and the associated log that the installer created if the and properties specified the creation of a new event log and source. - Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) in uninstall mode. The tool automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the event log being uninstalled. + Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) in uninstall mode. The tool automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the event log being uninstalled. - An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> diff --git a/xml/System.Diagnostics/EventLogTraceListener.xml b/xml/System.Diagnostics/EventLogTraceListener.xml index d837f2a6cee..6abeda08f65 100644 --- a/xml/System.Diagnostics/EventLogTraceListener.xml +++ b/xml/System.Diagnostics/EventLogTraceListener.xml @@ -36,9 +36,9 @@ can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or, for a .NET Framework app, specify it in the application configuration file. + An instance of this can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or, for a .NET Framework app, specify it in the application configuration file. -To add an using a .NET Framework application configuration file, edit the file that corresponds to the name of your application. In this file, insert an element for a type. The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. +To add an using a .NET Framework application configuration file, edit the file that corresponds to the name of your application. In this file, insert an element for a type. The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. ```xml @@ -55,7 +55,7 @@ To add an using a .NET Framework ``` > [!NOTE] -> If the for the event log that is associated with the instance does not exist, a new event source is created. To create an event source in Windows Vista, Windows XP Professional, or Windows Server 2003, you must have administrative privileges. +> If the for the event log that is associated with the instance does not exist, a new event source is created. To create an event source in Windows Vista, Windows XP Professional, or Windows Server 2003, you must have administrative privileges. > > The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > @@ -63,13 +63,13 @@ To add an using a .NET Framework The class provides the property to get or set the event log that receives the tracing or debugging output, and the property to hold the name of the . - The method closes the event log so it no longer receives tracing or debugging output. The and methods write a message to the event log. + The method closes the event log so it no longer receives tracing or debugging output. The and methods write a message to the event log. > [!NOTE] > To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. ## Examples - The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. + The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogTraceListener/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogTraceListener/Overview/source.vb" id="Snippet1"::: @@ -484,11 +484,11 @@ To add an using a .NET Framework ## Remarks > [!IMPORTANT] -> The methods are not intended to be called by application code. They are called by methods of the , , and classes to output trace data. +> The methods are not intended to be called by application code. They are called by methods of the , , and classes to output trace data. - The method, like the method is intended for automated tools but also allows the attaching of additional objects, for example an exception instance, to the trace. + The method, like the method is intended for automated tools but also allows the attaching of additional objects, for example an exception instance, to the trace. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object, formatted as a string, using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object, formatted as a string, using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -564,13 +564,13 @@ To add an using a .NET Framework ## Remarks > [!IMPORTANT] -> The methods are not intended to be called by application code. They are called by methods of the , , and classes to output trace data. +> The methods are not intended to be called by application code. They are called by methods of the , , and classes to output trace data. - The method, like the method is intended for automated tools but also allows the attaching of additional objects, for example an exception instance, to the trace. + The method, like the method is intended for automated tools but also allows the attaching of additional objects, for example an exception instance, to the trace. The `severity` and `id` parameter data is used to create an object, which is written to the event log with the data from the array of data objects. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object array, formatted as a string array, using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object array, formatted as a string array, using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -648,11 +648,11 @@ To add an using a .NET Framework ## Remarks > [!IMPORTANT] -> The methods are not intended to be called by application code. These methods are called by methods of the , , and classes to write trace data. +> The methods are not intended to be called by application code. These methods are called by methods of the , , and classes to write trace data. - The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. + The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `message` data using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `message` data using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -730,11 +730,11 @@ To add an using a .NET Framework ## Remarks > [!IMPORTANT] -> The methods are not intended to be called by application code. These methods are called by methods of the , , and classes to write trace data. +> The methods are not intended to be called by application code. These methods are called by methods of the , , and classes to write trace data. - The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. + The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log, using the method, with the message obtained from the `format` and `args` parameters. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message for the event log. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log, using the method, with the message obtained from the `format` and `args` parameters. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message for the event log. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index 344a43d7728..6d8eb78d45c 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -55,7 +55,7 @@ You can create an object in y ``` - The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. If an attempt is made to write to a file that is being used or is unavailable, a GUID suffix is automatically added to the file name. @@ -69,10 +69,10 @@ You can create an object in y |`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table.| |`Computer`|None|Always present.|This element represents the value of the property.| |`Correlation`|`ActivityID`|Always present.|If `ActivityID` is not specified, the default is an empty GUID.| -||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the `Trace` method call.|The `RelatedActivityID` attribute corresponds to the `relatedActivityId` parameter of the method.| +||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the `Trace` method call.|The `RelatedActivityID` attribute corresponds to the `relatedActivityId` parameter of the method.| |`Data`|None|Always present.|This element represents parameter input (`data`). One element is provided for each data object. In the case of event logs, the `Data` element contains escaped XML data. In the case of data logs, the `Data` element contains unescaped data. The data log output uses the `ToString` method of the passed-in data objects.| |`Event`|None|Always present.|This element contains a trace event.| -|`EventData`|None|Present for event logs.|This element represents parameter input (`message`, `args`). It contains `Data` elements with escaped XML data that is created by calling the method.| +|`EventData`|None|Present for event logs.|This element represents parameter input (`message`, `args`). It contains `Data` elements with escaped XML data that is created by calling the method.| |`EventID`|None|Always present.|This element represents parameter input (`id`).| |`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the .| ||`ThreadID`|Present when `ProcessID` is present.|The `ThreadID` attribute is specified in the .| @@ -84,9 +84,9 @@ You can create an object in y |`System`|`Name`|Always present.|| |`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| |`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| -|`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| +|`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| - The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the `UserData` element, which contains user-provided, unescaped data. The `UserData` element is a result of calls to the method. + The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the `UserData` element, which contains user-provided, unescaped data. The `UserData` element is a result of calls to the method. |Escaped character|Value| |-----------------------|-----------| @@ -145,7 +145,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/.ctor/program.vb" id="Snippet1"::: @@ -185,7 +185,7 @@ You can create an object in y constructor. + The following code example demonstrates how to use the constructor. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/.ctor/program.vb" id="Snippet2"::: @@ -232,7 +232,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/.ctor/program.vb" id="Snippet3"::: @@ -275,7 +275,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/.ctor/program.vb" id="Snippet4"::: @@ -324,7 +324,7 @@ You can create an object in y For performance considerations, `bufferSize` and `maximumFileSize` should be multiples of 1024 bytes. `maximumFileSize` is not an absolute value; it is a threshold that can be exceeded up to the size of the last message. ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/.ctor/program.vb" id="Snippet5"::: @@ -378,7 +378,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet2"::: @@ -540,7 +540,7 @@ You can create an object in y class. Using any other attribute causes a configuration exception. The method for the returns the following string array values: "bufferSize", "logRetentionOption", "maximumFileSize", and "maximumNumberOfFiles". + The custom attributes that are returned by this method can be used in the XML configuration file to control the behavior of an instance of the class. Using any other attribute causes a configuration exception. The method for the returns the following string array values: "bufferSize", "logRetentionOption", "maximumFileSize", and "maximumNumberOfFiles". ]]> @@ -893,7 +893,7 @@ You can create an object in y method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. @@ -974,10 +974,10 @@ You can create an object in y method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . + The method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . > [!IMPORTANT] -> The method should not be called by application code. It is intended to be used by a object to emit the trace information for its method. +> The method should not be called by application code. It is intended to be used by a object to emit the trace information for its method. ]]> @@ -1009,7 +1009,7 @@ You can create an object in y method is called to log the message as an event. + The method is called to log the message as an event. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. @@ -1044,7 +1044,7 @@ You can create an object in y method is called to log the message as an event. + The method is called to log the message as an event. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. diff --git a/xml/System.Diagnostics/EventSourceCreationData.xml b/xml/System.Diagnostics/EventSourceCreationData.xml index e135301dd96..4a97dd05003 100644 --- a/xml/System.Diagnostics/EventSourceCreationData.xml +++ b/xml/System.Diagnostics/EventSourceCreationData.xml @@ -38,11 +38,11 @@ ## Remarks Use the class to configure a new source for writing localized entries to an event log. It is not necessary to use this class to read from an event log. - This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. + This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. - Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. + Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. - Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. + Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configurations. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. @@ -50,11 +50,11 @@ To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. - You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes string values directly to the event log, you do not need to set these properties. + You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes string values directly to the event log, you do not need to set these properties. - The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. + The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. - If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files and use that source in the method to write strings directly to the event log using that source. + If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files and use that source in the method to write strings directly to the event log using that source. @@ -107,23 +107,23 @@ instance, configure the instance properties for your application, and call the method. After the source is registered, you can write entries from the source using the or methods. + To write entries to an event log, you must first create an event source for the event log. To register a new source, initialize an instance, configure the instance properties for your application, and call the method. After the source is registered, you can write entries from the source using the or methods. - You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes string values directly to the event log, you do not need to set these properties. + You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes string values directly to the event log, you do not need to set these properties. - The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files and use that source in the method to write strings directly to the event log. + The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files and use that source in the method to write strings directly to the event log. The following table shows initial property values for an . |Property|Initial Value| |--------------|-------------------| -||The `source` parameter.| -||The `logName` parameter.| -||The local computer (".").| -||Zero| -||`null` (`Nothing` in Visual Basic).| -||`null` (`Nothing` in Visual Basic).| -||`null` (`Nothing` in Visual Basic).| +||The `source` parameter.| +||The `logName` parameter.| +||The local computer (".").| +||Zero| +||`null` (`Nothing` in Visual Basic).| +||`null` (`Nothing` in Visual Basic).| +||`null` (`Nothing` in Visual Basic).| @@ -293,9 +293,9 @@ SVC_UPDATE.EXE and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide further information on the event. For example, your application can define separate categories for different components or different operations. + Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide further information on the event. For example, your application can define separate categories for different components or different operations. - Event categories are optional; if your application does not use categories, do not set the and properties. + Event categories are optional; if your application does not use categories, do not set the and properties. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -473,9 +473,9 @@ SVC_UPDATE.EXE and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide further information on the event. For example, your application can define separate categories for different components or different operations. + Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide further information on the event. For example, your application can define separate categories for different components or different operations. - Event categories are optional; if your application does not use categories, do not set the and properties. + Event categories are optional; if your application does not use categories, do not set the and properties. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -658,7 +658,7 @@ SVC_UPDATE.EXE To target an existing log for the new source, set the property to the existing event log name. To create a new event log for the source, you must set the property. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. The first 8 characters of the event log name must be different from the first 8 characters of existing names of event logs on the specified computer. - The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. @@ -719,7 +719,7 @@ SVC_UPDATE.EXE value cannot be an empty string. If the machine name is not explicitly set, it defaults to the local computer ("."). + The value cannot be an empty string. If the machine name is not explicitly set, it defaults to the local computer ("."). When registering a source on a remote computer, you must have administrative rights on that computer to write the registry values with sufficient permissions. @@ -786,9 +786,9 @@ SVC_UPDATE.EXE ## Remarks Use the property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. - Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized message resource file based on current language settings. + Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized message resource file based on current language settings. - The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. + The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. @@ -965,7 +965,7 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer fills in the placeholders using the corresponding strings from the and formats the event log message for the localized event entry. + Use the property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer fills in the placeholders using the corresponding strings from the and formats the event log message for the localized event entry. For example, the following section of a message text file defines a string with a parameter placeholder: @@ -976,7 +976,7 @@ Severity = Success Facility = Application SymbolicName = COMPONENT_STARTING Language=English -Component %%6050 is starting. +Component %`50 is starting. . ``` @@ -992,7 +992,7 @@ TRIGGER.EXE . ``` - The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. + The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. If your application writes event message strings directly to the event log, or if your property does not contain messages with parameter insertion placeholders, do not set the property. @@ -1169,7 +1169,7 @@ SVC_UPDATE.EXE method uses the , , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. + The source name is often the name of the application, or the name of a component within a large application. The method uses the , , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. After the registry values for the source are created, your application can use the source to write entries to the configured event log. diff --git a/xml/System.Diagnostics/EventTypeFilter.xml b/xml/System.Diagnostics/EventTypeFilter.xml index 80f33f3c16f..30bd097f150 100644 --- a/xml/System.Diagnostics/EventTypeFilter.xml +++ b/xml/System.Diagnostics/EventTypeFilter.xml @@ -51,7 +51,7 @@ ## Remarks One of several different types of filters can be assigned to a trace listener through the property to provide a layer of screening beyond that provided by the . The filter can be used to control the event types that are produced by the listener. - This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. + This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. To set the event type at which to begin tracing in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. diff --git a/xml/System.Diagnostics/FileVersionInfo.xml b/xml/System.Diagnostics/FileVersionInfo.xml index d28f3b94edf..53983f8dc4b 100644 --- a/xml/System.Diagnostics/FileVersionInfo.xml +++ b/xml/System.Diagnostics/FileVersionInfo.xml @@ -58,15 +58,15 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. - Use the method of this class to get a containing information about a file, then look at the properties for information about the file. The property provides version information about the file. The , , , , and properties provide version information for the product that the specified file is a part of. Call to get a partial list of properties and their values for this file. + Use the method of this class to get a containing information about a file, then look at the properties for information about the file. The property provides version information about the file. The , , , , and properties provide version information for the product that the specified file is a part of. Call to get a partial list of properties and their values for this file. The properties are based on version resource information built into the file. Version resources are often built into binary files such as .exe or .dll files; text files do not have version resource information. @@ -78,7 +78,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it prints the file description and version number to the console. + The following example calls to get the for the Notepad. Then it prints the file description and version number to the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/Overview/source.vb" id="Snippet1"::: @@ -145,7 +145,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it prints the comments in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the comments in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/Comments/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/Comments/source.vb" id="Snippet1"::: @@ -205,7 +205,7 @@ to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/CompanyName/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/CompanyName/source.vb" id="Snippet1"::: @@ -266,20 +266,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the third set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FileBuildPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FileBuildPart/source.vb" id="Snippet1"::: @@ -344,7 +344,7 @@ to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FileDescription/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FileDescription/source.vb" id="Snippet1"::: @@ -405,20 +405,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the first set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FileMajorPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FileMajorPart/source.vb" id="Snippet1"::: @@ -483,20 +483,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the second set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FileMinorPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FileMinorPart/source.vb" id="Snippet1"::: @@ -559,7 +559,7 @@ to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FileName/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FileName/source.vb" id="Snippet1"::: @@ -620,20 +620,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the last set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/FilePrivatePart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/FilePrivatePart/source.vb" id="Snippet1"::: @@ -700,18 +700,18 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A file version number is a 64-bit number that holds the version number for a file as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. ## Examples - The following example calls to get the for the Notepad. Then it prints the file description and version number in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the file description and version number in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/Overview/source.vb" id="Snippet1"::: @@ -773,7 +773,7 @@ to get the for Notepad and displays the file description and version number in the console window. + The following example calls to get the for Notepad and displays the file description and version number in the console window. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/Overview/source.vb" id="Snippet1"::: @@ -860,7 +860,7 @@ to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/InternalName/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/InternalName/source.vb" id="Snippet1"::: @@ -921,7 +921,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it displays the state of the Boolean in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it displays the state of the Boolean in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/IsDebug/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/IsDebug/source.vb" id="Snippet1"::: @@ -975,7 +975,7 @@ to get the for the Notepad. Then it displays the state of the Boolean in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it displays the state of the Boolean in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/IsPatched/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/IsPatched/source.vb" id="Snippet1"::: @@ -1029,7 +1029,7 @@ to get the for the Notepad. Then it displays whether this version is a prerelease version in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it displays whether this version is a prerelease version in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/IsPreRelease/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/IsPreRelease/source.vb" id="Snippet1"::: @@ -1083,12 +1083,12 @@ will describe how this version of the file differs from the standard version. + If this value is `true`, will describe how this version of the file differs from the standard version. ## Examples - The following example calls to get the for the Notepad. Then it displays the private build information in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it displays the private build information in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/IsPrivateBuild/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/IsPrivateBuild/source.vb" id="Snippet1"::: @@ -1148,7 +1148,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it displays whether this version is a special build version in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it displays whether this version is a special build version in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/IsSpecialBuild/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/IsSpecialBuild/source.vb" id="Snippet1"::: @@ -1264,7 +1264,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/LegalCopyright/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/LegalCopyright/source.vb" id="Snippet1"::: @@ -1329,7 +1329,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/LegalTrademarks/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/LegalTrademarks/source.vb" id="Snippet1"::: @@ -1394,7 +1394,7 @@ ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/OriginalFilename/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/OriginalFilename/source.vb" id="Snippet1"::: @@ -1454,12 +1454,12 @@ is `true`. + This information is present when is `true`. ## Examples - The following example calls to get the for the Notepad. Then it prints the private build information in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the private build information in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/PrivateBuild/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/PrivateBuild/source.vb" id="Snippet1"::: @@ -1521,20 +1521,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A product version number is a 64-bit number that holds the version number as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the third set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductBuildPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductBuildPart/source.vb" id="Snippet1"::: @@ -1599,20 +1599,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A product version number is a 64-bit number that holds the version number as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the first set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductMajorPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductMajorPart/source.vb" id="Snippet1"::: @@ -1676,20 +1676,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A product version number is a 64-bit number that holds the version number as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the second set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductMinorPart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductMinorPart/source.vb" id="Snippet1"::: @@ -1752,7 +1752,7 @@ to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductName/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductName/source.vb" id="Snippet1"::: @@ -1813,20 +1813,20 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A product version number is a 64-bit number that holds the version number as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. This property gets the last set of 16 bits. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductPrivatePart/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductPrivatePart/source.vb" id="Snippet1"::: @@ -1892,18 +1892,18 @@ ## Remarks Typically, a version number is displayed as "major number.minor number.build number.private part number". A product version number is a 64-bit number that holds the version number as follows: -- The first 16 bits are the number. +- The first 16 bits are the number. -- The next 16 bits are the number. +- The next 16 bits are the number. -- The third set of 16 bits are the number. +- The third set of 16 bits are the number. -- The last 16 bits are the number. +- The last 16 bits are the number. ## Examples - The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ProductVersion/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ProductVersion/source.vb" id="Snippet1"::: @@ -1967,12 +1967,12 @@ is `true`, must specify how this file differs from the standard version of the file. + If is `true`, must specify how this file differs from the standard version of the file. ## Examples - The following example calls to get the for the Notepad. Then it prints the special build information in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it prints the special build information in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/SpecialBuild/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/SpecialBuild/source.vb" id="Snippet1"::: @@ -2033,7 +2033,7 @@ to get the for the Notepad. Then it calls to print a list of the file version information in a text box. This code assumes `textBox1` has been instantiated. + The following example calls to get the for the Notepad. Then it calls to print a list of the file version information in a text box. This code assumes `textBox1` has been instantiated. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/FileVersionInfo/ToString/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/FileVersionInfo/ToString/source.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/InstanceDataCollection.xml b/xml/System.Diagnostics/InstanceDataCollection.xml index 722f189e05d..f73cd230936 100644 --- a/xml/System.Diagnostics/InstanceDataCollection.xml +++ b/xml/System.Diagnostics/InstanceDataCollection.xml @@ -37,12 +37,12 @@ class represents a collection containing all the instance data for a counter. This collection is contained in the when using the method. + The class represents a collection containing all the instance data for a counter. This collection is contained in the when using the method. ## Examples - The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by to an array of objects. The example also displays the instance data associated with each of each . + The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by to an array of objects. The example also displays the instance data associated with each of each . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet1"::: @@ -151,7 +151,7 @@ ## Examples - The following code example accepts a category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. It then uses the method to determine if the specified instance exists, using the default single-instance name if none is entered. + The following code example accepts a category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. It then uses the method to determine if the specified instance exists, using the default single-instance name if none is entered. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.vb" id="Snippet2"::: @@ -202,7 +202,7 @@ method to convert an into an array of objects. The values of the and properties of each element of the array are passed to a function for further processing. + The following code example uses the method to convert an into an array of objects. The values of the and properties of each element of the array are passed to a function for further processing. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet4"::: diff --git a/xml/System.Diagnostics/InstanceDataCollectionCollection.xml b/xml/System.Diagnostics/InstanceDataCollectionCollection.xml index 6c2daac463c..0e3795c5c4a 100644 --- a/xml/System.Diagnostics/InstanceDataCollectionCollection.xml +++ b/xml/System.Diagnostics/InstanceDataCollectionCollection.xml @@ -37,7 +37,7 @@ class represents the collection returned from the method. This collection contains all the counter and instance data. The collection contains an object for each counter. Each object contains the performance data for all counters for that instance. Thus, the data is indexed by counter name and then by instance name. + The class represents the collection returned from the method. This collection contains all the counter and instance data. The collection contains an object for each counter. Each object contains the performance data for all counters for that instance. Thus, the data is indexed by counter name and then by instance name. @@ -146,12 +146,12 @@ ## Remarks The `counterName` parameter is case-insensitive. - Each object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. returns `true` if there is an object whose associated counter has the name specified by the `counterName` parameter. + Each object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. returns `true` if there is an object whose associated counter has the name specified by the `counterName` parameter. ## Examples - The following code example accepts a category name and counter name from the command line. It gets the for the and then uses the method to determine if the specified counter exists. If the counter exists, the example gets the associated and displays the instance names from the collection. + The following code example accepts a category name and counter name from the command line. It gets the for the and then uses the method to determine if the specified counter exists. If the counter exists, the example gets the associated and displays the instance names from the collection. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitermcontains.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitemcontains.vb" id="Snippet2"::: @@ -202,7 +202,7 @@ method to convert an into an array of objects. Each element of the array is passed to a function for further processing. + The following code example uses the method to convert an into an array of objects. Each element of the array is passed to a function for further processing. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet5"::: diff --git a/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml b/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml index 0d114452693..511f35fc27f 100644 --- a/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml +++ b/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml @@ -117,7 +117,7 @@ constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies + The description you specify in the constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies ]]> diff --git a/xml/System.Diagnostics/OverflowAction.xml b/xml/System.Diagnostics/OverflowAction.xml index 49e5e018c7e..6009605fcd1 100644 --- a/xml/System.Diagnostics/OverflowAction.xml +++ b/xml/System.Diagnostics/OverflowAction.xml @@ -41,7 +41,7 @@ - New entries will overwrite older entries. - Use the method to set the overflow behavior for an . Check the current configured behavior of an through its property. + Use the method to set the overflow behavior for an . Check the current configured behavior of an through its property. > [!WARNING] > The `OverwriteOlder` behavior is deprecated. Using this value might cause the Event Log to behave as if the `DoNotOverwrite` value was used instead, which will cause events to be discarded when the log is full. diff --git a/xml/System.Diagnostics/PerformanceCounter.xml b/xml/System.Diagnostics/PerformanceCounter.xml index 9ce5f36ddce..18d5d861d84 100644 --- a/xml/System.Diagnostics/PerformanceCounter.xml +++ b/xml/System.Diagnostics/PerformanceCounter.xml @@ -63,19 +63,19 @@ There are numerous predefined counters listed in the Windows Performance Monitor's [Add Counters dialog box](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749266(v=ws.11)). To learn about the .NET Framework performance counters, see [Performance Counters](/dotnet/framework/debug-trace-profile/performance-counters). - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. > [!IMPORTANT] > In versions 1.0 and 1.1 of .NET Framework, this class requires immediate callers to be fully trusted. Starting with .NET Framework version 2.0, this class requires for specific actions. It is strongly recommended that not be granted to semi-trusted code. The ability to read and write performance counters allows code to perform actions such as enumerating executing processes and obtaining information about them. > > In addition, passing a object to less-trusted code can create a security issue. Never pass performance counter objects, such as a or , to less trusted code. - To read from a performance counter, create an instance of the class, set the , , and, optionally, the or properties, and then call the method to take a performance counter reading. + To read from a performance counter, create an instance of the class, set the , , and, optionally, the or properties, and then call the method to take a performance counter reading. - To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. + To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. The counter is the mechanism by which performance data is collected. The registry stores the names of all the counters, each of which is related to a specific area of system functionality. Examples include a processor's busy time, memory usage, or the number of bytes received over a network connection. @@ -85,7 +85,7 @@ In certain cases, several copies of the same category can exist. For example, several processes and threads run simultaneously, and some computers contain more than one processor. The category copies are called category instances, and each instance has a set of standard counters assigned to it. If a category can have more than one instance, an instance specification must be included in the counter information. - To obtain performance data for counters that required an initial or previous value for performing the necessary calculation, call the method twice and use the information returned as your application requires. + To obtain performance data for counters that required an initial or previous value for performing the necessary calculation, call the method twice and use the information returned as your application requires. > [!NOTE] > Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. If the FileMappingSize value is not present, the `fileMappingSize` attribute value for the `performanceCounters` element specified in the Machine.config file is used, causing additional overhead for configuration file processing. You can realize a performance improvement for application startup by setting the file mapping size in the registry. For more information about the file mapping size, see [<performanceCounters>](/dotnet/framework/configure-apps/file-schema/trace-debug/performancecounters-element). @@ -146,15 +146,15 @@ , , and properties to empty strings (""), and sets the property to the local computer, ("."). + This overload of the constructor sets the , , and properties to empty strings (""), and sets the property to the local computer, ("."). - This constructor does not initialize the performance counter, so it does not associate the instance with an existing counter on the local computer. To point to a specific performance counter, set the , , and, optionally, the and properties before reading any other properties or attempting to read from a counter. To write to a performance counter, set the property to `false`. + This constructor does not initialize the performance counter, so it does not associate the instance with an existing counter on the local computer. To point to a specific performance counter, set the , , and, optionally, the and properties before reading any other properties or attempting to read from a counter. To write to a performance counter, set the property to `false`. > [!NOTE] > The attribute applied to this member has the following property value: | . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -211,9 +211,9 @@ Use this overload to access a counter on the local computer that belongs to a category containing a single performance counter category instance. If you attempt to use this constructor to point this instance to a category that contains multiple instances, the constructor throws an exception. This overload can access any read-only or read/write counter, but does so in a read-only mode. A instance created using this overload cannot write to the counter, even if the counter itself is read/write. - This overload of the constructor sets the and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). + This overload of the constructor sets the and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). - This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. + This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -299,9 +299,9 @@ Use this overload to access a read-only or read/write counter on the local computer that belongs to a category containing a single performance counter category instance. If you attempt to use this constructor to point this instance to a category that contains multiple instances, the constructor throws an exception. - This overload of the constructor sets the , , and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). + This overload of the constructor sets the , , and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). - This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. + This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. > [!NOTE] > You can use this overload to connect to a system counter, but you cannot write to a system counter. Therefore, setting `readOnly` to `false` when connecting to a system counter causes the constructor to throw an exception. @@ -396,13 +396,13 @@ ## Remarks The parameter strings are not case-sensitive. - This overload of the constructor sets the , , and properties to the values you pass in, and sets the property to the local computer, ".". + This overload of the constructor sets the , , and properties to the values you pass in, and sets the property to the local computer, ".". - This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance you point to is not valid, calling the constructor throws an exception. + This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance you point to is not valid, calling the constructor throws an exception. This overload can access any read-only or read/write counter, but does so in a read-only mode. A instance created using this overload cannot write to the counter, even if the counter itself is read/write. - To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. + To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -488,14 +488,14 @@ Use this overload to access a performance counter in either read-only or read/write mode. - This overload of the constructor sets the , , and properties to the values you pass in, it and sets the property to the local computer, ".". + This overload of the constructor sets the , , and properties to the values you pass in, it and sets the property to the local computer, ".". - This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. + This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. > [!NOTE] > You can use this overload to connect to a system counter, but you cannot write to a system counter. Therefore, setting `readOnly` to `false` when connecting to a system counter causes the constructor to throw an exception. - To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. + To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -586,14 +586,14 @@ ## Remarks The parameter strings are not case-sensitive. - This overload of the constructor sets the , , , and properties to the values you pass in. + This overload of the constructor sets the , , , and properties to the values you pass in. - This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the specified computer. The values that you pass in for the , , and properties must point to an existing performance counter. If the performance counter instance you point to is not valid, calling the constructor throws an exception. This overload can access any read-only or read/write counter, but does so in a read-only mode. A instance created using this overload cannot write to the counter, even if the counter itself is read/write. + This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the specified computer. The values that you pass in for the , , and properties must point to an existing performance counter. If the performance counter instance you point to is not valid, calling the constructor throws an exception. This overload can access any read-only or read/write counter, but does so in a read-only mode. A instance created using this overload cannot write to the counter, even if the counter itself is read/write. > [!NOTE] > You cannot write to remote performance counters. There is no overload that allows you to specify a read/write instance of the class that connects to a remote computer. - To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. + To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -685,7 +685,7 @@ method ends the initialization. Using the and methods prevents the component from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to start the initialization of a component that is used on a form or by another component. The method ends the initialization. Using the and methods prevents the component from being used before it is fully initialized. ]]> @@ -761,7 +761,7 @@ is displayed in the `Performance Object` field of Performance Counter Manager MMC snap in's `Add Counter` dialog box. + The is displayed in the `Performance Object` field of Performance Counter Manager MMC snap in's `Add Counter` dialog box. A performance counter monitors the behavior of a category, or performance object, on a computer. Categories include physical components (such as processors, disks, and memory) and system objects (such as processes and threads). System counters that are related to the same performance object are grouped into a category that indicates their common focus. When you create an instance of the class, you first indicate the category with which the component will interact, and then you choose a counter from that category. @@ -770,7 +770,7 @@ Although your system makes many more counter categories available, the categories that you will probably interact with most frequently are the Cache, Memory, Objects, PhysicalDisk, Process, Processor, Server, System, and Thread categories. ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -817,7 +817,7 @@ instance with a performance counter that resides on the server, the system initializes the instance and allocates memory to contain counter sample information. The method frees the resources allocated by the object. + When you associate this instance with a performance counter that resides on the server, the system initializes the instance and allocates memory to contain counter sample information. The method frees the resources allocated by the object. ]]> @@ -908,12 +908,12 @@ text when a user selects a counter from the counters list and clicks the Explain button. + The Add Counters dialog box of the Performance Counter Manager MMC snap in displays the text when a user selects a counter from the counters list and clicks the Explain button. - When you create a new counter, use the text to describe what the counter monitors do so the user can determine whether to add the counter to the System Monitor's display. + When you create a new counter, use the text to describe what the counter monitors do so the user can determine whether to add the counter to the System Monitor's display. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1073,10 +1073,10 @@ |Track a higher-capacity number of items or operations per second.|`RateOfCountsPerSecond64`|Tracking orders received per second on a site with very high volume.| |Calculate the average time to perform a process or to process an item|`AverageTimer32`|Calculate the average time an order takes to be processed.| - When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. + When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1136,10 +1136,10 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> @@ -1287,7 +1287,7 @@ method starts the initialization. Using the and methods prevents the component from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to end the initialization of a component that is used on a form or by another component. The method starts the initialization. Using the and methods prevents the component from being used before it is fully initialized. ]]> @@ -1333,10 +1333,10 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> @@ -1402,15 +1402,15 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ## Examples - The following code example demonstrates how to use the method to add increments to a counter. This code example is part of a larger example for the class. + The following code example demonstrates how to use the method to add increments to a counter. This code example is part of a larger example for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet3"::: @@ -1475,10 +1475,10 @@ must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. + If the performance counter category is created with the .NET Framework version 1.0 or 1.1, it uses global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] -> If the value of the property is , the value for the performance counter must be . +> If the value of the property is , the value for the performance counter must be . ]]> @@ -1567,7 +1567,7 @@ If this instance points to a noncustom category, you can choose from only the existing category instances. You can create new category instances only in custom categories, which allow you to define as many counters and category instances as you need. - To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. + To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] > Do not use the characters "(", ")", "#", "\\", or "/" in the instance name. If any of these characters are used, the Performance Console (see [Runtime Profiling](/dotnet/framework/debug-trace-profile/runtime-profiling)) may not correctly display the instance values. @@ -1587,7 +1587,7 @@ ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -1703,7 +1703,7 @@ This method is generally used for counters that contain uncalculated values. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1715,7 +1715,7 @@ ## Examples - The following code example demonstrates how to use the method to obtain the next uncalculated value of a counter. This code example is part of a larger example for the class. + The following code example demonstrates how to use the method to obtain the next uncalculated value of a counter. This code example is part of a larger example for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet3"::: @@ -1770,7 +1770,7 @@ ## Remarks > [!NOTE] -> If the calculated value of a counter depends on two counter reads, the first read operation returns 0.0. Resetting the performance counter properties to specify a different counter is equivalent to creating a new performance counter, and the first read operation using the new properties returns 0.0. The recommended delay time between calls to the method is one second, to allow the counter to perform the next incremental read. +> If the calculated value of a counter depends on two counter reads, the first read operation returns 0.0. Resetting the performance counter properties to specify a different counter is equivalent to creating a new performance counter, and the first read operation using the new properties returns 0.0. The recommended delay time between calls to the method is one second, to allow the counter to perform the next incremental read. > [!NOTE] > To read performance counters, you must have administrative privileges. In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. @@ -1778,7 +1778,7 @@ ## Examples - The following code example creates an counter and uses the method to display the counter's values over a time period. + The following code example creates an counter and uses the method to display the counter's values over a time period. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/NextValue/elapsedtime.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/NextValue/elapsedtime.vb" id="Snippet2"::: @@ -1842,15 +1842,15 @@ ## Remarks If the counter type is a 32-bit size and you attempt to set this property to a value that is too large to fit, the property truncates the value to 32 bits. When reading custom counters on the local computer, using the property rather than a calculated value can produce significantly better performance in scenarios where the raw value is sufficient. - If the counter that you are reading is read-only, getting the property samples the counter at the time that the property is called. This action is equivalent to making an initial call to the method. If you subsequently call , you can perform calculations on the values that both calls returned. + If the counter that you are reading is read-only, getting the property samples the counter at the time that the property is called. This action is equivalent to making an initial call to the method. If you subsequently call , you can perform calculations on the values that both calls returned. Because system counters are read-only, you can get but not set their raw values. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1937,7 +1937,7 @@ should always `true`. You cannot write to a system counter. + For a system counter, should always `true`. You cannot write to a system counter. ]]> @@ -1988,12 +1988,12 @@ You can remove an instance only for a custom counter. All system counters are read-only, so attempting to remove one of them throws an exception. > [!NOTE] -> To avoid a possible race condition when the performance counter shared memory is released, it is recommended that the method be called from the event handler. +> To avoid a possible race condition when the performance counter shared memory is released, it is recommended that the method be called from the event handler. - To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. + To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> diff --git a/xml/System.Diagnostics/PerformanceCounterCategory.xml b/xml/System.Diagnostics/PerformanceCounterCategory.xml index e17cb720173..c8a72ee1261 100644 --- a/xml/System.Diagnostics/PerformanceCounterCategory.xml +++ b/xml/System.Diagnostics/PerformanceCounterCategory.xml @@ -43,7 +43,7 @@ The instance's property is displayed in the Performance Object field of the Performance Viewer application's Add Counter dialog box. - The class provides several methods for interacting with counters and categories on the computer. The methods enable you to define custom categories. The method provides a way to remove categories from the computer. The method enables you to view the list of categories, while retrieves all the counter and instance data associated with a single category. + The class provides several methods for interacting with counters and categories on the computer. The methods enable you to define custom categories. The method provides a way to remove categories from the computer. The method enables you to view the list of categories, while retrieves all the counter and instance data associated with a single category. A performance counter publishes performance data about an application. Categories include physical components (such as processors, disks, and memory) and system objects (such as processes and threads). System counters that are related to the same performance object are grouped into a category that indicates their common focus. When you create an instance of the class, you first indicate the category with which the component will interact, and then you choose a counter from that category. @@ -52,7 +52,7 @@ Although your system makes many more counter categories available, the categories that you will probably interact with most frequently are the Cache, Memory, Objects, PhysicalDisk, Process, Processor, Server, System, and Thread categories. > [!IMPORTANT] -> The method in the class will release the counter and, if the reuse option is selected for that category, the instance of the counter will be reused. This could cause a race condition if another process or even another part of the code is trying to write to the counter instance. +> The method in the class will release the counter and, if the reuse option is selected for that category, the instance of the counter will be reused. This could cause a race condition if another process or even another part of the code is trying to write to the counter instance. > [!NOTE] > It is strongly recommended that new performance counter categories be created during the installation of the application, not during the execution of the application. This allows time for the operating system to refresh its list of registered performance counter categories. If the list has not been refreshed, the attempt to use the category will fail. @@ -63,11 +63,11 @@ ## Examples - The following code example determines whether a and its exist on the local computer or on another computer. If these objects do not exist on the local computer, the example optionally creates them. It uses the method to determine whether the exists. If the does not exist and no counter name is specified, or if the computer is a remote machine, the example exits. + The following code example determines whether a and its exist on the local computer or on another computer. If these objects do not exist on the local computer, the example optionally creates them. It uses the method to determine whether the exists. If the does not exist and no counter name is specified, or if the computer is a remote machine, the example exits. - If a name is provided, the example uses the method and displays the result to the user. If the does not exist, the user can delete and re-create the with the new . If the user does so, the category is deleted using the method. + If a name is provided, the example uses the method and displays the result to the user. If the does not exist, the user can delete and re-create the with the new . If the user does so, the category is deleted using the method. - If requested, the example now creates the new and using the method. If an instance name is specified, the example uses the method and displays the result. + If requested, the example now creates the new and using the method. If an instance name is specified, the example uses the method and displays the result. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Overview/perfcountercatcreateexist.cs" id="Snippet27"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/Overview/perfcountercatcreateexist.vb" id="Snippet27"::: @@ -285,7 +285,7 @@ with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + The following code example creates a with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatprops.vb" id="Snippet8"::: @@ -342,7 +342,7 @@ with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + The following code example creates a with the . It prompts the user for the and computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatprops.vb" id="Snippet8"::: @@ -460,7 +460,7 @@ > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It creates a object using the appropriate . It then uses the method to determine whether the specified exists, and informs the user. + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It creates a object using the appropriate . It then uses the method to determine whether the specified exists, and informs the user. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatobjexists.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatobjcountexists.vb" id="Snippet4"::: @@ -535,7 +535,7 @@ > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcounterexists.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcountexists.vb" id="Snippet8"::: @@ -610,7 +610,7 @@ > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples - The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. + The following code example determines whether a exists. It gets a category name, counter name, and computer name from the command line, if they are given. It uses the static overloads of the method to determine whether the specified name exists in the . The overload is selected based on whether a computer name is provided. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcounterexists.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatcountexists.vb" id="Snippet8"::: @@ -795,7 +795,7 @@ > In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples - The following code example shows the use of the method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second. + The following code example shows the use of the method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/Create/program.vb" id="Snippet2"::: @@ -987,7 +987,7 @@ ## Examples - The following code example shows the use of the method. The example shows how to create a custom, single instance performance counter category. + The following code example shows the use of the method. The example shows how to create a custom, single instance performance counter category. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/Create/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/Create/program.vb" id="Snippet3"::: @@ -1070,7 +1070,7 @@ ## Examples - The following code example uses the method to delete a and the objects that it contains. + The following code example uses the method to delete a and the objects that it contains. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatDelete.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatdelete.vb" id="Snippet6"::: @@ -1141,7 +1141,7 @@ method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. + Use of the method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1211,7 +1211,7 @@ method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. + Use of the method can result in a noticeable performance penalty while all performance counters on the machine are checked for availability. If you are only writing to a performance counter, you can avoid the global search for performance counters by creating the performance counter when the application is installed and assuming the category exists when accessing the counter. There is no way to avoid the performance counter search when reading from performance counters. > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1310,7 +1310,7 @@ ## Examples - The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. + The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountergetcat.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcat.vb" id="Snippet2"::: @@ -1374,7 +1374,7 @@ ## Examples - The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. + The following code example uses the method to return an array of objects from the local computer or a specified computer. It converts the array into an array of category names, which it sorts and displays for the user. The overload is selected based on whether a computer name was specified. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountergetcat.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcat.vb" id="Snippet2"::: @@ -1445,7 +1445,7 @@ ## Examples - The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. + The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. This overload fails unless it is used with a single-instance category. @@ -1515,9 +1515,9 @@ ## Examples - The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. + The following code example gets a list of the objects in a . It first creates a with the appropriate constructor, based on whether a computer name was specified. It then uses the method to return an array of objects, selecting the overload based on whether an instance name was specified. - This overload fails unless it is used with a category that contains instances. + This overload fails unless it is used with a category that contains instances. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcount.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetcount.vb" id="Snippet4"::: @@ -1583,7 +1583,7 @@ ## Examples - The following code example gets a list of the objects in a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to return the instance names as an array of , which it sorts and displays. + The following code example gets a list of the objects in a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to return the instance names as an array of , which it sorts and displays. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetinst.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/GetCategories/perfcountercatgetinst.vb" id="Snippet6"::: @@ -1652,7 +1652,7 @@ is not `static`. It requires you to create a object and to set the property. + This overload of is not `static`. It requires you to create a object and to set the property. > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1664,7 +1664,7 @@ ## Examples - The following code example determines whether a instance exists within a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to determine whether the specified instance exists, then informs the user. If no instance name is specified, the example uses the default single-instance name. + The following code example determines whether a instance exists within a . It first creates a object, using the appropriate constructor based on whether a computer name was specified. It then uses to determine whether the specified instance exists, then informs the user. If no instance name is specified, the example uses the default single-instance name. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcounterobjinstexists.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatobjinstexists.vb" id="Snippet2"::: @@ -1743,7 +1743,7 @@ ## Examples - The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. + The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.vb" id="Snippet10"::: @@ -1823,7 +1823,7 @@ ## Examples - The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. + The following code example uses the static overloads of to determine whether the given instance exists in the . The overload is selected based on whether a computer name is specified. If no instance name is specified, the example uses the default single-instance name. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/CounterExists/perfcountercatstatinstexists.vb" id="Snippet10"::: @@ -1890,7 +1890,7 @@ with the constructor. It prompts the user for the and the computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. + The following code example creates a with the constructor. It prompts the user for the and the computer names, then sets the and properties from the entered values. It then displays the values of the , , and properties, or it displays an error message if the cannot be accessed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterCategory/.ctor/perfCounterCatProps.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterCategory/.ctor/perfcountercatprops.vb" id="Snippet8"::: @@ -1939,7 +1939,7 @@ property before you call . + You must set the property before you call . Reading the entire category at once can be as efficient as reading a single counter because of the way that the system provides the data. @@ -1953,7 +1953,7 @@ ## Examples - The following code example creates a for a specified name. It then uses to return an that contains instance data for all the instances of the objects within the . + The following code example creates a for a specified name. It then uses to return an that contains instance data for all the instances of the objects within the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet6"::: diff --git a/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml b/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml index 61231f80a30..40d17e5d729 100644 --- a/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml +++ b/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml @@ -38,7 +38,7 @@ The default behavior is Global, which specifies the removal of the performance counter instance when no counters are using the process category. > [!NOTE] -> If the property is , the value for the performance counter must be `Global`. +> If the property is , the value for the performance counter must be `Global`. ]]> diff --git a/xml/System.Diagnostics/PresentationTraceSources.xml b/xml/System.Diagnostics/PresentationTraceSources.xml index 7fe740bd4fe..4143f59ed81 100644 --- a/xml/System.Diagnostics/PresentationTraceSources.xml +++ b/xml/System.Diagnostics/PresentationTraceSources.xml @@ -24,47 +24,47 @@ Provides debug tracing support that is specifically targeted for Windows Presentation Foundation (WPF) applications. - - - - - - - - - - - - - - - - - - -``` - + + + + + + + + + + + + + + + + + + +``` + ]]> @@ -248,11 +248,11 @@ switchName="SourceSwitch" > Gets the value of the attached property for a specified element. The property value for the element. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - + is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). + ]]> @@ -285,11 +285,11 @@ switchName="SourceSwitch" > Gets an hwnd host trace source. An hwnd host trace source. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - + is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). + ]]> @@ -471,11 +471,11 @@ switchName="SourceSwitch" > The needed value. Sets the value of the attached property to a specified element. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - + is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). + ]]> @@ -561,11 +561,11 @@ switchName="SourceSwitch" > Identifies the attached property. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - + is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). + ]]> diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index 17abad93c55..6a31af630e8 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -99,18 +99,18 @@ The component is a useful tool for starting, stopping, controlling, and monitoring apps. You can use the component, to obtain a list of the processes that are running, or you can start a new process. A component is used to access system processes. After a component has been initialized, it can be used to obtain information about the running process. Such information includes the set of threads, the loaded modules (.dll and .exe files), and performance information such as the amount of memory the process is using. - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface documentation. + This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface documentation. [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] > [!NOTE] > 32-bit processes cannot access the modules of a 64-bit process. If you try to get information about a 64-bit process from a 32-bit process, you will get a exception. A 64-bit process, on the other hand, can access the modules of a 32-bit process. - The process component obtains information about a group of properties all at once. After the component has obtained information about one member of any group, it will cache the values for the other properties in that group and not obtain new information about the other members of the group until you call the method. Therefore, a property value is not guaranteed to be any newer than the last call to the method. The group breakdowns are operating-system dependent. + The process component obtains information about a group of properties all at once. After the component has obtained information about one member of any group, it will cache the values for the other properties in that group and not obtain new information about the other members of the group until you call the method. Therefore, a property value is not guaranteed to be any newer than the last call to the method. The group breakdowns are operating-system dependent. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. + A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. On macOS, the following properties return 0: @@ -123,13 +123,13 @@ On macOS, the following properties return 0: ## .NET Core Notes - In .NET Framework, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, .NET Core may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. + In .NET Framework, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, .NET Core may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: 1. Retrieve the object from the property. -2. Pass the object to the method to make the additional encodings supported by the encoding provider available. +2. Pass the object to the method to make the additional encodings supported by the encoding provider available. The class will then automatically use the default system encoding rather than UTF8, provided that you have registered the encoding provider before calling any methods. @@ -142,7 +142,7 @@ On macOS, the following properties return 0: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/Overview/processstart.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Process/Overview/processstart.vb" id="Snippet1"::: - The following example uses the class itself and a static method to start a process. + The following example uses the class itself and a static method to start a process. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstartstatic.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/Overview/processstartstatic.fs"::: @@ -205,15 +205,15 @@ On macOS, the following properties return 0: ## Remarks If you do not specify the property, the default is the local computer, ("."). - You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. + You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. - If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. + If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. - When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. + When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. - Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. + Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. - You can create a component by using the constructor, one of the static overloads, or any of the , , or methods. After you have done so, you have a view into the associated process. This is not a dynamic view that updates itself automatically when the process properties have changed in memory. Instead, you must call for the component to update the property information in your application. + You can create a component by using the constructor, one of the static overloads, or any of the , , or methods. After you have done so, you have a view into the associated process. This is not a dynamic view that updates itself automatically when the process properties have changed in memory. Instead, you must call for the component to update the property information in your application. ]]> @@ -275,11 +275,11 @@ On macOS, the following properties return 0: ## Remarks The value returned by this property represents the most recently refreshed base priority of the process. To get the most up to date base priority, you need to call method first. - The of the process is the starting priority for threads created within the associated process. You can view information about the base priority through the System Monitor's Priority Base counter. + The of the process is the starting priority for threads created within the associated process. You can view information about the base priority through the System Monitor's Priority Base counter. Based on the time elapsed or other boosts, the operating system can change the base priority when a process should be placed ahead of others. - The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. + The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. |BasePriority|PriorityClass| |------------------|-------------------| @@ -358,28 +358,28 @@ On macOS, the following properties return 0: stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables the designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables the designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - Follow these steps to perform asynchronous read operations on for a : + Follow these steps to perform asynchronous read operations on for a : -1. Set to `false`. +1. Set to `false`. -2. Set to `true`. +2. Set to `true`. 3. Add your event handler to the event. The event handler must match the delegate signature. 4. Start the . -5. Call for the . This call starts asynchronous read operations on . +5. Call for the . This call starts asynchronous read operations on . - When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. + When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. - You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. + You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -457,35 +457,35 @@ On macOS, the following properties return 0: stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - Follow these steps to perform asynchronous read operations on for a : + Follow these steps to perform asynchronous read operations on for a : -1. Set to `false`. +1. Set to `false`. -2. Set to `true`. +2. Set to `true`. 3. Add your event handler to the event. The event handler must match the delegate signature. 4. Start the . -5. Call for the . This call starts asynchronous read operations on . +5. Call for the . This call starts asynchronous read operations on . - When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. + When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. - You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. + You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. ## Examples - The following example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. + The following example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. - The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.fs" id="Snippet1"::: @@ -558,11 +558,11 @@ On macOS, the following properties return 0: starts an asynchronous read operation on the stream. ends the asynchronous read operation. + starts an asynchronous read operation on the stream. ends the asynchronous read operation. - After canceling, you can resume the asynchronous read operation by calling again. + After canceling, you can resume the asynchronous read operation by calling again. - When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to will be lost. If you re-enable the event handler with a call to , asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: + When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to will be lost. If you re-enable the event handler with a call to , asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: ```csharp // At this point the DataReceivedEventHandler(ErrorHandler1) @@ -581,7 +581,7 @@ process.BeginErrorReadLine(); ``` > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . @@ -651,11 +651,11 @@ process.BeginErrorReadLine(); starts an asynchronous read operation on the stream. ends the asynchronous read operation. + starts an asynchronous read operation on the stream. ends the asynchronous read operation. - After canceling, you can resume asynchronous read operations by calling again. + After canceling, you can resume asynchronous read operations by calling again. - When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to is saved in a buffer. If you re-enable the event handler with a call to , the saved output is sent to the event handler and asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: + When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to is saved in a buffer. If you re-enable the event handler with a call to , the saved output is sent to the event handler and asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: ```csharp // At this point the DataReceivedEventHandler(OutputHandler1) @@ -674,7 +674,7 @@ process.BeginOutputReadLine(); ``` > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . @@ -738,10 +738,10 @@ process.BeginOutputReadLine(); method causes the process to stop waiting for exit if it was waiting, closes the process handle, and clears process-specific properties. does not close the standard output, input, and error readers and writers in case they are being referenced externally. + The method causes the process to stop waiting for exit if it was waiting, closes the process handle, and clears process-specific properties. does not close the standard output, input, and error readers and writers in case they are being referenced externally. > [!NOTE] -> The method calls . Placing the object in a `using` block disposes of resources without the need to call . +> The method calls . Placing the object in a `using` block disposes of resources without the need to call . @@ -801,11 +801,11 @@ process.BeginOutputReadLine(); sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. The request to exit the process by calling does not force the application to quit. The application can ask for user verification before quitting, or it can refuse to quit. To force the application to quit, use the method. The behavior of is identical to that of a user closing an application's main window using the system menu. Therefore, the request to exit the process by closing the main window does not force the application to quit immediately. + When a process is executing, its message loop is in a wait state. The message loop executes every time a Windows message is sent to the process by the operating system. Calling sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. The request to exit the process by calling does not force the application to quit. The application can ask for user verification before quitting, or it can refuse to quit. To force the application to quit, use the method. The behavior of is identical to that of a user closing an application's main window using the system menu. Therefore, the request to exit the process by closing the main window does not force the application to quit immediately. - Data edited by the process or resources allocated to the process can be lost if you call . causes an abnormal process termination, and should be used only when necessary. enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. If fails, you can use to terminate the process. is the only way to terminate processes that do not have graphical interfaces. + Data edited by the process or resources allocated to the process can be lost if you call . causes an abnormal process termination, and should be used only when necessary. enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. If fails, you can use to terminate the process. is the only way to terminate processes that do not have graphical interfaces. - You can call and only for processes that are running on the local computer. You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. + You can call and only for processes that are running on the local computer. You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. @@ -970,18 +970,18 @@ process.BeginOutputReadLine(); property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. +The property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. > [!NOTE] > If you're using Visual Studio and double-click a component in your project, an event delegate and event handler are automatically generated. Additional code sets the property to `false`. You must change this property to `true` for your event handler to execute when the associated process exits. -If the component's value is `true`, or when is `false` and a check is invoked by the component, the component can access the administrative information for the associated process, which remains stored by the operating system. Such information includes the and the . +If the component's value is `true`, or when is `false` and a check is invoked by the component, the component can access the administrative information for the associated process, which remains stored by the operating system. Such information includes the and the . -After the associated process exits, the of the component no longer points to an existing process resource. Instead, it can only be used to access the operating system's information about the process resource. The operating system is aware that there are handles to exited processes that haven't been released by components, so it keeps the and information in memory. +After the associated process exits, the of the component no longer points to an existing process resource. Instead, it can only be used to access the operating system's information about the process resource. The operating system is aware that there are handles to exited processes that haven't been released by components, so it keeps the and information in memory. -There's a cost associated with watching for a process to exit. If is `true`, the event is raised when the associated process terminates. Your procedures for the event run at that time. +There's a cost associated with watching for a process to exit. If is `true`, the event is raised when the associated process terminates. Your procedures for the event run at that time. -Sometimes, your application starts a process but doesn't require notification of its closure. For example, your application can start Notepad to allow the user to perform text editing but make no further use of the Notepad application. You can choose to avoid notification when the process exits because it's not relevant to the continued operation of your application. Setting to `false` can save system resources. +Sometimes, your application starts a process but doesn't require notification of its closure. For example, your application can start Notepad to allow the user to perform text editing but make no further use of the Notepad application. You can choose to avoid notification when the process exits because it's not relevant to the continued operation of your application. Setting to `false` can save system resources. ## Examples The following code example creates a process that prints a file. It sets the property to cause the process to raise the event when it exits. The event handler displays process information. @@ -1045,7 +1045,7 @@ The following code example creates a process that prints a file. It sets the on the component. Call when you no longer need access to these processes that run in special mode. + Some operating system processes run in a special mode. Attempting to read properties of or attach to these processes is not possible unless you have called on the component. Call when you no longer need access to these processes that run in special mode. ]]> @@ -1110,9 +1110,9 @@ The following code example creates a process that prints a file. It sets the event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. + The event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. - The event only occurs during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . + The event only occurs during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . > [!NOTE] > The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. Note that specifying a timeout by using the overload does *not* ensure the output buffer has been flushed. @@ -1193,20 +1193,20 @@ The following code example creates a process that prints a file. It sets the to get the status that the system process returned when it exited. You can use the exit code much like an integer return value from a `main()` procedure. + Use to get the status that the system process returned when it exited. You can use the exit code much like an integer return value from a `main()` procedure. - The value for a process reflects the specific convention implemented by the application developer for that process. If you use the exit code value to make decisions in your code, be sure that you know the exit code convention used by the application process. + The value for a process reflects the specific convention implemented by the application developer for that process. If you use the exit code value to make decisions in your code, be sure that you know the exit code convention used by the application process. - Developers usually indicate a successful exit by an value of zero, and designate errors by nonzero values that the calling method can use to identify the cause of an abnormal process termination. It is not necessary to follow these guidelines, but they are the convention. + Developers usually indicate a successful exit by an value of zero, and designate errors by nonzero values that the calling method can use to identify the cause of an abnormal process termination. It is not necessary to follow these guidelines, but they are the convention. - If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. + If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. > [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . +> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . - You can use the or the method to cause an associated process to exit. + You can use the or the method to cause an associated process to exit. - There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification relies on calling the method to pause the processing of your application until the associated component exits. Asynchronous notification relies on the event. When using asynchronous notification, must be set to `true` for the component to receive notification that the process has exited. + There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification relies on calling the method to pause the processing of your application until the associated component exits. Asynchronous notification relies on the event. When using asynchronous notification, must be set to `true` for the component to receive notification that the process has exited. @@ -1287,12 +1287,12 @@ The following code example creates a process that prints a file. It sets the event indicates that the associated process exited. This occurrence means either that the process terminated (aborted) or successfully closed. This event can occur only if the value of the property is `true`. - There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification means calling the method to block the current thread until the process exits. Asynchronous notification uses the event, which allows the calling thread to continue execution in the meantime. In the latter case, must be set to `true` for the calling application to receive the Exited event. + There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification means calling the method to block the current thread until the process exits. Asynchronous notification uses the event, which allows the calling thread to continue execution in the meantime. In the latter case, must be set to `true` for the calling application to receive the Exited event. - When the operating system shuts down a process, it notifies all other processes that have registered handlers for the Exited event. At this time, the handle of the process that just exited can be used to access some properties such as and that the operating system maintains until it releases that handle completely. + When the operating system shuts down a process, it notifies all other processes that have registered handlers for the Exited event. At this time, the handle of the process that just exited can be used to access some properties such as and that the operating system maintains until it releases that handle completely. > [!NOTE] -> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . +> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . For more information about the use of the event in Windows Forms applications, see the property. @@ -1367,7 +1367,7 @@ The following code example creates a process that prints a file. It sets the property throws an exception. Use before getting the property to determine whether the associated process has terminated. + If the process has not terminated, attempting to retrieve the property throws an exception. Use before getting the property to determine whether the associated process has terminated. @@ -1432,7 +1432,7 @@ The following code example creates a process that prints a file. It sets the instance and associate it with the process resource on the local computer. - Like the similar , , and methods, associates an existing resource with a new component. + Like the similar , , and methods, associates an existing resource with a new component. @@ -1514,9 +1514,9 @@ The following code example creates a process that prints a file. It sets the component and associate it with a process resource on the local computer. The process resource must already exist on the computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. + Use this method to create a new component and associate it with a process resource on the local computer. The process resource must already exist on the computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. - On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. + On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. The `processId` parameter is an (a 32-bit signed integer), although the underlying Windows API uses a `DWORD` (an unsigned 32-bit integer) for similar APIs. This is for historical reasons. @@ -1586,9 +1586,9 @@ The following code example creates a process that prints a file. It sets the component and associate it with a process resource on a remote computer on the network. The process resource must already exist on the specified computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. + Use this method to create a new component and associate it with a process resource on a remote computer on the network. The process resource must already exist on the specified computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. - On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. + On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. If you do not specify a `machineName`, the local computer is used. Alternatively, you can specify the local computer by setting `machineName` to the value "." or to an empty string (""). @@ -1689,12 +1689,12 @@ The following code example creates a process that prints a file. It sets the components and associate them with all the process resources on the local computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. + Use this method to create an array of new components and associate them with all the process resources on the local computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. - If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. + If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. > [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . @@ -1775,14 +1775,14 @@ The following code example creates a process that prints a file. It sets the components and associate them with all the process resources on the specified (usually remote) computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. + Use this method to create an array of new components and associate them with all the process resources on the specified (usually remote) computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. - If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. + If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. - This overload of the method is generally used to retrieve the list of process resources running on a remote computer on the network, but you can specify the local computer by passing ".". + This overload of the method is generally used to retrieve the list of process resources running on a remote computer on the network, but you can specify the local computer by passing ".". > [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . @@ -1890,11 +1890,11 @@ The following code example creates a process that prints a file. It sets the components and associate them with all the process resources that are running the same executable file on the local computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. + Use this method to create an array of new components and associate them with all the process resources that are running the same executable file on the local computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. - The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. + The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. - Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. + Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. @@ -1986,15 +1986,15 @@ The following code example creates a process that prints a file. It sets the components and associate them with all the process resources that are running the same executable file on the specified computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. + Use this method to create an array of new components and associate them with all the process resources that are running the same executable file on the specified computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. - The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. + The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. - Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. + Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. You can use this overload to get processes on the local computer as well as on a remote computer. Use "." to specify the local computer. Another overload exists that uses the local computer by default. - You can access processes on remote computers only to view information, such as statistics, about the processes. You cannot close, terminate (using ), or start processes on remote computers. + You can access processes on remote computers only to view information, such as statistics, about the processes. You cannot close, terminate (using ), or start processes on remote computers. @@ -2082,9 +2082,9 @@ There are problems accessing the performance counter APIs used to get process in ## Remarks An application can obtain a handle to a process that can be used as a parameter to many process-information and control functions. You can use this handle to initialize a or to call native methods with platform invoke. - This process handle is private to an application. In other words, process handles cannot be shared. A process also has a process that, unlike the , is unique and, therefore, valid throughout the system. + This process handle is private to an application. In other words, process handles cannot be shared. A process also has a process that, unlike the , is unique and, therefore, valid throughout the system. - Only processes started through a call to set the property of the corresponding instances. + Only processes started through a call to set the property of the corresponding instances. ]]> @@ -2226,12 +2226,12 @@ There are problems accessing the performance counter APIs used to get process in indicates that the associated process has terminated, either normally or abnormally. You can request or force the associated process to exit by calling or . If a handle is open to the process, the operating system releases the process memory when the process has exited, but retains administrative information about the process, such as the handle, exit code, and exit time. To get this information, you can use the and properties. These properties are populated automatically for processes that were started by this component. The administrative information is released when all the components that are associated with the system process are destroyed and hold no more handles to the exited process. + A value of `true` for indicates that the associated process has terminated, either normally or abnormally. You can request or force the associated process to exit by calling or . If a handle is open to the process, the operating system releases the process memory when the process has exited, but retains administrative information about the process, such as the handle, exit code, and exit time. To get this information, you can use the and properties. These properties are populated automatically for processes that were started by this component. The administrative information is released when all the components that are associated with the system process are destroyed and hold no more handles to the exited process. - A process can terminate independently of your code. If you started the process using this component, the system updates the value of automatically, even if the associated process exits independently. + A process can terminate independently of your code. If you started the process using this component, the system updates the value of automatically, even if the associated process exits independently. > [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . +> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . @@ -2308,9 +2308,9 @@ There are problems accessing the performance counter APIs used to get process in is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. + The process is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. - You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. + You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. Process identifiers can be reused by the system. The property value is unique only while the associated process is running. After the process has terminated, the system can reuse the property value for an unrelated process. @@ -2319,7 +2319,7 @@ There are problems accessing the performance counter APIs used to get process in ## Examples - The following example demonstrates how to obtain the for all running instances of an application. The code creates a new instance of Notepad, lists all the instances of Notepad, and then allows the user to enter the number to remove a specific instance. + The following example demonstrates how to obtain the for all running instances of an application. The code creates a new instance of Notepad, lists all the instances of Notepad, and then allows the user to enter the number to remove a specific instance. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Id/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/Id/program.fs" id="Snippet1"::: @@ -2344,32 +2344,32 @@ There are problems accessing the performance counter APIs used to get process in ## Remarks -The `Kill` method forces a termination of the process, while only requests a termination. +The `Kill` method forces a termination of the process, while only requests a termination. When a process with a graphical interface is executing, its message loop is in a wait state. The message loop executes every time a Windows message is sent to the process by the operating system. -Calling sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. -The request to exit the process by calling does not force the application to quit. +Calling sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. +The request to exit the process by calling does not force the application to quit. The application can ask for user verification before quitting, or it can refuse to quit. To force the application to quit, use the `Kill` method. -The behavior of is identical to that of a user closing an application's main window using the system menu. +The behavior of is identical to that of a user closing an application's main window using the system menu. Therefore, the request to exit the process by closing the main window does not force the application to quit immediately. > [!NOTE] -> The method executes asynchronously. -> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. +> The method executes asynchronously. +> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. > [!NOTE] -> The method and the property do not reflect the status of descendant processes. -> When `Kill(entireProcessTree: true)` is used, and will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited. +> The method and the property do not reflect the status of descendant processes. +> When `Kill(entireProcessTree: true)` is used, and will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited. Data edited by the process or resources allocated to the process can be lost if you call `Kill`. `Kill` causes an abnormal process termination and should be used only when necessary. - enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. -If fails, you can use `Kill` to terminate the process. + enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. +If fails, you can use `Kill` to terminate the process. `Kill` is the only way to terminate processes that do not have graphical interfaces. -You can call `Kill` and only for processes that are running on the local computer. +You can call `Kill` and only for processes that are running on the local computer. You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. ]]> @@ -2552,7 +2552,7 @@ The calling process is a member of the associated process's descendant tree. on the component. Call when you no longer need access to these processes that run in special mode. + Some operating system processes run in a special mode. Attempting to read properties of or attach to these processes is not possible unless you have called on the component. Call when you no longer need access to these processes that run in special mode. ]]> @@ -2617,7 +2617,7 @@ The calling process is a member of the associated process's descendant tree., , or on remote computers. + You can view statistical data and process information for processes running on remote computers but you cannot call , , or on remote computers. > [!NOTE] > When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. @@ -2625,7 +2625,7 @@ The calling process is a member of the associated process's descendant tree., , and properties for each instance. + To use the following example you must first start at least one instance of Notepad on a remote computer. The example requests the name of the remote computer on which Notepad is running, and then displays the respective , , and properties for each instance. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/MachineName/process_getprocessesbyname2_2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/MachineName/process_getprocessesbyname2_2.fs" id="Snippet2"::: @@ -2772,13 +2772,13 @@ If no main module is found, it could be because the process hasn't finished load form). You must use the method to refresh the object to get the most up to date main window handle if it has changed. In general, because the window handle is cached, use beforehand to guarantee that you'll retrieve the current handle. + The main window is the window opened by the process that currently has the focus (the form). You must use the method to refresh the object to get the most up to date main window handle if it has changed. In general, because the window handle is cached, use beforehand to guarantee that you'll retrieve the current handle. You can get the property only for processes that are running on the local computer. The property is a value that uniquely identifies the window that is associated with the process. - A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window, the value is zero. The value is also zero for processes that have been hidden, that is, processes that are not visible in the taskbar. This can be the case for processes that appear as icons in the notification area, at the far right of the taskbar. + A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window, the value is zero. The value is also zero for processes that have been hidden, that is, processes that are not visible in the taskbar. This can be the case for processes that appear as icons in the notification area, at the far right of the taskbar. - If you have just started a process and want to use its main window handle, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, an exception will be thrown. + If you have just started a process and want to use its main window handle, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, an exception will be thrown. ]]> @@ -2841,12 +2841,12 @@ If no main module is found, it could be because the process hasn't finished load is zero), or if the system can't determine that there's a main window (such as may be the case on some Unix platforms), is an empty string (""). + A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window (so that is zero), or if the system can't determine that there's a main window (such as may be the case on some Unix platforms), is an empty string (""). - If you have just started a process and want to use its main window title, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, the system throws an exception. + If you have just started a process and want to use its main window title, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, the system throws an exception. > [!NOTE] -> The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the method to refresh the object to get the most up to date main window handle if it has changed. +> The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the method to refresh the object to get the most up to date main window handle if it has changed. @@ -2951,7 +2951,7 @@ If no main module is found, it could be because the process hasn't finished load A process has minimum and maximum working set sizes. Each time a process resource is created, the system reserves an amount of memory equal to the minimum working set size for the process. The virtual memory manager attempts to keep at least the minimum amount of memory resident when the process is active, but it never keeps more than the maximum size. - The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. + The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. > [!NOTE] > When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. @@ -3063,7 +3063,7 @@ If no main module is found, it could be because the process hasn't finished load A process has minimum and maximum working set sizes. Each time a process resource is created, the system reserves an amount of memory equal to the minimum working set size for the process. The virtual memory manager attempts to keep at least the minimum amount of memory resident when the process is active, but it never keeps more than the maximum size. - The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. + The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. > [!NOTE] > When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. @@ -3151,7 +3151,7 @@ If no main module is found, it could be because the process hasn't finished load A process can load multiple modules into memory. For example,.exe files that load additional .dll files have multiple modules. - After starting the process, this collection is empty until the system has loaded the process. If the process has a main window, you can call before retrieving this property to ensure that the collection is nonempty when you get the list. + After starting the process, this collection is empty until the system has loaded the process. If the process has a main window, you can call before retrieving this property to ensure that the collection is nonempty when you get the list. ]]> @@ -3347,19 +3347,19 @@ If no main module is found, it could be because the process hasn't finished load is the API method that raises the event. Calling causes the event to occur and is the only way to raise the event using the component. is primarily used when deriving classes from the component. + is the API method that raises the event. Calling causes the event to occur and is the only way to raise the event using the component. is primarily used when deriving classes from the component. - As an alternative to , you can write your own event handler. You create your own event handler delegate and your own event-handling method. + As an alternative to , you can write your own event handler. You create your own event handler delegate and your own event-handling method. > [!NOTE] -> If you are using the Visual Studio environment, an event handler delegate (AddOnExited) and an event-handling method (Process1_Exited) are created for you when you drag a component onto a form and double-click the icon. The code you create to run when the event occurs is entered into the Process1_Exited procedure. You do not need to create the member, because it is implemented for you. +> If you are using the Visual Studio environment, an event handler delegate (AddOnExited) and an event-handling method (Process1_Exited) are created for you when you drag a component onto a form and double-click the icon. The code you create to run when the event occurs is entered into the Process1_Exited procedure. You do not need to create the member, because it is implemented for you. Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). ## Examples - The following example shows how to use the method in a derived class. + The following example shows how to use the method in a derived class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/OnExited/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/OnExited/program.fs" id="Snippet1"::: @@ -3428,19 +3428,19 @@ If no main module is found, it could be because the process hasn't finished load event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. + The event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. - The event is enabled during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . + The event is enabled during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. ## Examples - The following example illustrates how to perform asynchronous read operations on the redirected stream of the `ipconfig` command. + The following example illustrates how to perform asynchronous read operations on the redirected stream of the `ipconfig` command. - The example creates an event delegate for the `OutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and saves it in an output string that's later shown in the example's console window. + The example creates an event delegate for the `OutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and saves it in an output string that's later shown in the example's console window. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/datareceivedevent.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/DataReceivedEventArgs/Overview/datareceivedevent.fs" id="Snippet4"::: @@ -4232,7 +4232,7 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The value returned by this property represents the most recently refreshed temporary priority boost. To get the most up to date value, you need to call method first. - When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to `false`. + When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to `false`. > [!NOTE] > Boosting the priority too high can drain resources from essential operating system and network functions, causing problems with other operating system tasks. @@ -4303,11 +4303,11 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The value returned by this property represents the most recently refreshed priority of the process. To get the most up to date priority, you need to call method first. - A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the enumeration, which lets you set the process priority to , , , , , or . Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. + A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the enumeration, which lets you set the process priority to , , , , , or . Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. The property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the property to set the priority of a process. To change the priority, use the property, which gets or sets the overall priority category for the process. - The priority class cannot be viewed using System Monitor. The following table shows the relationship between the and values. + The priority class cannot be viewed using System Monitor. The following table shows the relationship between the and values. |BasePriority|PriorityClass| |------------------|-------------------| @@ -4616,7 +4616,7 @@ If no main module is found, it could be because the process hasn't finished load > [!NOTE] > On Windows 2000 operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. - You can call , passing it an executable file name, to retrieve an array that contains every running instance on the specified computer. You can use this array, for example, to shut down all the running instances of the executable file. + You can call , passing it an executable file name, to retrieve an array that contains every running instance on the specified computer. You can use this array, for example, to shut down all the running instances of the executable file. ]]> @@ -4695,9 +4695,9 @@ If no main module is found, it could be because the process hasn't finished load In Windows 2000 and later, a thread in a process can migrate from processor to processor, with each migration reloading the processor cache. Under heavy system loads, specifying which processor should run a specific thread can improve performance by reducing the number of times the processor cache is reloaded. The association between a processor and a thread is called the processor affinity. - Each processor is represented as a bit. Bit 0 is processor one, bit 1 is processor two, and so forth. If you set a bit to the value 1, the corresponding processor is selected for thread assignment. When you set the value to zero, the operating system's scheduling algorithms set the thread's affinity. When the value is set to any nonzero value, the value is interpreted as a bitmask that specifies those processors eligible for selection. + Each processor is represented as a bit. Bit 0 is processor one, bit 1 is processor two, and so forth. If you set a bit to the value 1, the corresponding processor is selected for thread assignment. When you set the value to zero, the operating system's scheduling algorithms set the thread's affinity. When the value is set to any nonzero value, the value is interpreted as a bitmask that specifies those processors eligible for selection. - The following table shows a selection of values for an eight-processor system. + The following table shows a selection of values for an eight-processor system. |Bitmask|Binary value|Eligible processors| |-------------|------------------|-------------------------| @@ -4767,9 +4767,9 @@ If no main module is found, it could be because the process hasn't finished load is called, the first request for information about each property causes the process component to obtain a new value from the associated process. + After is called, the first request for information about each property causes the process component to obtain a new value from the associated process. - When a component is associated with a process resource, the property values of the are immediately populated according to the status of the associated process. If the information about the associated process subsequently changes, those changes are not reflected in the component's cached values. The component is a snapshot of the process resource at the time they are associated. To view the current values for the associated process, call the method. + When a component is associated with a process resource, the property values of the are immediately populated according to the status of the associated process. If the information about the associated process subsequently changes, those changes are not reflected in the component's cached values. The component is a snapshot of the process resource at the time they are associated. To view the current values for the associated process, call the method. @@ -4842,7 +4842,7 @@ If no main module is found, it could be because the process hasn't finished load If a process has a user interface, the property contacts the user interface to determine whether the process is responding to user input. If the interface does not respond immediately, the property returns `false`. Use this property to determine whether the interface of the associated process has stopped responding. - If the process does not have a , this property returns `true`. + If the process does not have a , this property returns `true`. @@ -5041,30 +5041,30 @@ If no main module is found, it could be because the process hasn't finished load writes text to its standard error stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + When a writes text to its standard error stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. - The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process. + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process. -The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. +The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardOutput/write500lines.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardError/stderror-sync.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardError/stderror-sync.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standarderror/stderror-sync.vb"::: -There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: @@ -5072,7 +5072,7 @@ There is a similar issue when you read all text from both the standard output an You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -5153,15 +5153,15 @@ You can use asynchronous read operations to avoid these dependencies and their d can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. + A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. ## Examples - The following example illustrates how to redirect the stream of a process. The example starts the `sort` command with redirected input. It then prompts the user for text, and passes that to the `sort` process by means of the redirected stream. The `sort` results are displayed to the user on the console. + The following example illustrates how to redirect the stream of a process. The example starts the `sort` command with redirected input. It then prompts the user for text, and passes that to the `sort` process by means of the redirected stream. The `sort` results are displayed to the user on the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardInput/process_standardinput.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardInput/process_standardinput.fs" id="Snippet1"::: @@ -5233,30 +5233,30 @@ You can use asynchronous read operations to avoid these dependencies and their d writes text to its standard stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + When a writes text to its standard stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. - The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process. + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process. -The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. +The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardOutput/write500lines.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-sync.vb"::: -There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.fs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: @@ -5264,7 +5264,7 @@ There is a similar issue when you read all text from both the standard output an You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. > [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. @@ -5357,31 +5357,31 @@ There is a similar issue when you read all text from both the standard output an component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. + Use this overload to start a process resource and associate it with the current component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. You can start a ClickOnce application by specifying the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] > [!NOTE] -> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. +> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. - This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. + This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. - The other overloads of the method are `static` members. You do not need to create an instance of the component before you call those overloads of the method. Instead, you can call for the class itself, and a new component is created if the process was started. Or, `null` is returned if a process was reused. The process resource is automatically associated with the new component that is returned by the method. + The other overloads of the method are `static` members. You do not need to create an instance of the component before you call those overloads of the method. Instead, you can call for the class itself, and a new component is created if the process was started. Or, `null` is returned if a process was reused. The process resource is automatically associated with the new component that is returned by the method. - The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. - In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. + In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5485,24 +5485,24 @@ The member > [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. + This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. - Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. You can start a ClickOnce application by specifying the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. - If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. + If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the start information for the process resource by using a instance. + Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the start information for the process resource by using a instance. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the `startInfo` parameter, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the `startInfo` parameter, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5614,24 +5614,24 @@ The member > [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. You can start a ClickOnce application by setting the `fileName` parameter to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. Starting a process by specifying its file name is similar to typing the information in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". - This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. + This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start. + Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5787,20 +5787,20 @@ The file specified in the could not be found. [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. Starting a process by specifying its file name and arguments is similar to typing the file name and command-line arguments in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. If the `fileName` parameter represents a command (.cmd) file, the `arguments` parameter must include either a "`/c`" or "`/k`" argument to specify whether the command window exits or remains after completion. - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start and command-line arguments to pass. + Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start and command-line arguments to pass. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5911,14 +5911,14 @@ The file specified in the could not be found. > [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -6022,14 +6022,14 @@ The file specified in the could not be found. [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. ]]> @@ -6105,20 +6105,20 @@ The file specified in the could not be found. represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". + represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. - If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. + If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. - You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . + You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . - You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. + You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. - When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. + When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. ## Examples - The following example populates a with the file to execute, the action performed on it and whether it should displays a user interface. For additional examples, refer to the reference pages for properties of the class. + The following example populates a with the file to execute, the action performed on it and whether it should displays a user interface. For additional examples, refer to the reference pages for properties of the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstart.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/Overview/processstart.fs" id="Snippet1"::: @@ -6270,11 +6270,11 @@ The file specified in the could not be found. is `null`, methods that handle the event are called on a thread from the system thread pool. For more information about system thread pools, see . + When is `null`, methods that handle the event are called on a thread from the system thread pool. For more information about system thread pools, see . - When the event is handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. + When the event is handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. - If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control that contains the . For example, if you place a on a designer for `Form1` (which inherits from ) the property of is set to the instance of `Form1`: + If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control that contains the . For example, if you place a on a designer for `Form1` (which inherits from ) the property of is set to the instance of `Form1`: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/SynchronizingObject/remarks.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/SynchronizingObject/remarks.fs" id="Snippet2"::: @@ -6781,16 +6781,16 @@ The file specified in the could not be found. ## Remarks makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. - This method instructs the component to wait an infinite amount of time for the process and event handlers to exit. This can cause an application to stop responding. For example, if you call for a process that has a user interface, the request to the operating system to terminate the associated process might not be handled if the process is written to never enter its message loop. + This method instructs the component to wait an infinite amount of time for the process and event handlers to exit. This can cause an application to stop responding. For example, if you call for a process that has a user interface, the request to the operating system to terminate the associated process might not be handled if the process is written to never enter its message loop. > [!NOTE] > In the .NET Framework 3.5 and earlier versions, the overload waited for milliseconds (approximately 24 days), not indefinitely. Also, previous versions did not wait for the event handlers to exit if the full time was reached. - This overload ensures that all processing has been completed, including the handling of asynchronous events for redirected standard output. You should use this overload after a call to the overload when standard output has been redirected to asynchronous event handlers. + This overload ensures that all processing has been completed, including the handling of asynchronous events for redirected standard output. You should use this overload after a call to the overload when standard output has been redirected to asynchronous event handlers. - When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. + When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. @@ -6867,18 +6867,18 @@ The file specified in the could not be found. makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. + makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. - This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. + This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. > [!NOTE] -> In the .NET Framework 3.5 and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. +> In the .NET Framework 3.5 and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. - When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. + When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. @@ -7120,11 +7120,11 @@ This method stores in the task it returns all non-usage exceptions that the meth to force the processing of your application to wait until the message loop has returned to the idle state. When a process with a user interface is executing, its message loop executes every time a Windows message is sent to the process by the operating system. The process then returns to the message loop. A process is said to be in an idle state when it is waiting for messages inside of a message loop. This state is useful, for example, when your application needs to wait for a starting process to finish creating its main window before the application communicates with that window. + Use to force the processing of your application to wait until the message loop has returned to the idle state. When a process with a user interface is executing, its message loop executes every time a Windows message is sent to the process by the operating system. The process then returns to the message loop. A process is said to be in an idle state when it is waiting for messages inside of a message loop. This state is useful, for example, when your application needs to wait for a starting process to finish creating its main window before the application communicates with that window. - If a process does not have a message loop, throws an . + If a process does not have a message loop, throws an . - The overload instructs the component to wait a finite amount of time for the process to become idle in the message loop. If the associated process has not become idle by the end of the interval because the loop is still processing messages, `false` is returned to the calling procedure. + The overload instructs the component to wait a finite amount of time for the process to become idle in the message loop. If the associated process has not become idle by the end of the interval because the loop is still processing messages, `false` is returned to the calling procedure. For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). diff --git a/xml/System.Diagnostics/ProcessModule.xml b/xml/System.Diagnostics/ProcessModule.xml index 878d3718ea9..d47a55a2089 100644 --- a/xml/System.Diagnostics/ProcessModule.xml +++ b/xml/System.Diagnostics/ProcessModule.xml @@ -77,7 +77,7 @@ A module is an executable file or a dynamic link library (DLL). Each process consists of one or more modules. You can use this class to get information about the module. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -141,7 +141,7 @@ class to obtain a object for each module in the collection. The and properties are used to display the module name and the memory address where each module was loaded. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the memory address where each module was loaded. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/BaseAddress/processmodule_baseaddress.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/BaseAddress/processmodule_baseaddress.vb" id="Snippet1"::: @@ -203,12 +203,12 @@ The module's entry point is the location of the function that is called during process startup, thread startup, process shutdown, and thread shutdown. While the entry point is not the address of the DllMain function, it should be close enough for most purposes. > [!NOTE] -> Due to changes in the way that Windows loads assemblies, will always return 0 on Windows 8 or Windows 8.1 and should not be relied on for those platforms. +> Due to changes in the way that Windows loads assemblies, will always return 0 on Windows 8 or Windows 8.1 and should not be relied on for those platforms. ## Examples - The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the name and the entry point address for each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the name and the entry point address for each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/EntryPointAddress/processmodule_entrypoint.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/EntryPointAddress/processmodule_entrypoint.vb" id="Snippet1"::: @@ -273,7 +273,7 @@ ## Examples - The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the full path information for each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the full path information for each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/FileName/processmodule_filename.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/FileName/processmodule_filename.vb" id="Snippet1"::: @@ -331,7 +331,7 @@ class to obtain a object for each module in the collection. The and properties are used to display the module name and the file version information for each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the file version information for each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/FileVersionInfo/processmodule_fileversioninfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/FileVersionInfo/processmodule_fileversioninfo.vb" id="Snippet1"::: @@ -390,12 +390,12 @@ does not include any additional memory allocations that the module makes once it is running; it includes only the size of the static code and data in the module file. + does not include any additional memory allocations that the module makes once it is running; it includes only the size of the static code and data in the module file. ## Examples - The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the amount of memory needed for each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the amount of memory needed for each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/ModuleMemorySize/processmodule_modulememorysize.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/ModuleMemorySize/processmodule_modulememorysize.vb" id="Snippet1"::: @@ -514,7 +514,7 @@ class to obtain a object for each module in the collection. The method is used to display the name for each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The method is used to display the name for each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/ToString/processmodule_tostring.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/ToString/processmodule_tostring.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/ProcessPriorityClass.xml b/xml/System.Diagnostics/ProcessPriorityClass.xml index f56cc1fec5e..6c5df36f461 100644 --- a/xml/System.Diagnostics/ProcessPriorityClass.xml +++ b/xml/System.Diagnostics/ProcessPriorityClass.xml @@ -46,13 +46,13 @@ Indicates the priority that the system associates with a process. This value, together with the priority value of each thread of the process, determines each thread's base priority level. - to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. - + to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. + ]]> diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index 4a99f7fec7f..ecd82334a00 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -66,9 +66,9 @@ In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. - Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. + Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. - Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. + Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. @@ -281,7 +281,7 @@ ## Remarks The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - You can change the or properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. + You can change the or properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -568,7 +568,7 @@ If you use this property to set command-line arguments, property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. + If the property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. .NET Core does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. @@ -699,7 +699,7 @@ If you use this property to set command-line arguments, property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + The environment variables contain search paths for files, directories for temporary files, application-specific options, and other similar information. Although you cannot directly set the property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. On .NET Framework applications, using the property is the same as using the property. @@ -783,7 +783,7 @@ If you use this property to set command-line arguments, property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + Although you cannot set the property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. ]]> @@ -857,7 +857,7 @@ If you use this property to set command-line arguments, [!NOTE] -> must be `true` if you want to set to `true`. +> must be `true` if you want to set to `true`. ]]> @@ -924,7 +924,7 @@ If you use this property to set command-line arguments, is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. + If is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. ]]> @@ -1026,7 +1026,7 @@ If you use this property to set command-line arguments, property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. + The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. @@ -1181,17 +1181,17 @@ If you use this property to set command-line arguments, [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. > [!NOTE] -> Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. +> Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET Framework garbage collector. For more information about secure strings and an example of how to obtain a password to set this property, see the class. > [!NOTE] -> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. +> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1324,31 +1324,31 @@ If you use this property to set command-line arguments, writes text to its standard error stream, that text is typically displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + When a writes text to its standard error stream, that text is typically displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. +> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. - The redirected stream can be read synchronously or asynchronously. Methods such as , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The redirected stream can be read synchronously or asynchronously. Methods such as , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. -The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. +The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardError/stderror-sync.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standarderror/stderror-sync.vb"::: -There is a similar issue when you read all text from both the standard output and standard error streams. The following C# code, for example, performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +There is a similar issue when you read all text from both the standard output and standard error streams. The following C# code, for example, performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: @@ -1435,17 +1435,17 @@ You can use asynchronous read operations to avoid these dependencies and their d can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input of a process. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. + A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input of a process. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. +> You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. ## Examples - The following example illustrates how to redirect the stream of a process. The `sort` command is a console application that reads and sorts text input. + The following example illustrates how to redirect the stream of a process. The `sort` command is a console application that reads and sorts text input. - The example starts the `sort` command with redirected input. It then prompts the user for text, and passes the text to the `sort` process through the redirected stream. The `sort` results are displayed to the user on the console. + The example starts the `sort` command with redirected input. It then prompts the user for text, and passes the text to the `sort` process through the redirected stream. The `sort` results are displayed to the user on the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardInput/process_standardinput.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Process/StandardInput/process_standardinput.vb" id="Snippet1"::: @@ -1523,31 +1523,31 @@ You can use asynchronous read operations to avoid these dependencies and their d writes text to its standard stream, that text is typically displayed on the console. By setting to `true` to redirect the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + When a writes text to its standard stream, that text is typically displayed on the console. By setting to `true` to redirect the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. +> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. - The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler (see ) for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler (see ) for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. -The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. +The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-sync.vb"::: -There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: @@ -1834,9 +1834,9 @@ You can use asynchronous read operations to avoid these dependencies and their d ## Remarks > [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. + If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1996,7 +1996,7 @@ You can use asynchronous read operations to avoid these dependencies and their d ## Remarks -Each file name extension has its own set of verbs, which can be obtained by using the property. For example, the "`print`" verb prints a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. +Each file name extension has its own set of verbs, which can be obtained by using the property. For example, the "`print`" verb prints a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. @@ -2251,16 +2251,16 @@ The following code example starts a new process by using the specified verb and ## Remarks > [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property. - The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. + The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. > [!NOTE] -> When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. +> When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. - When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. + When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. ]]> diff --git a/xml/System.Diagnostics/ProcessThread.xml b/xml/System.Diagnostics/ProcessThread.xml index 05b2b66f8b9..0c661a0193c 100644 --- a/xml/System.Diagnostics/ProcessThread.xml +++ b/xml/System.Diagnostics/ProcessThread.xml @@ -73,7 +73,7 @@ Use to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. @@ -148,7 +148,7 @@ is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. + The is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. @@ -326,7 +326,7 @@ value is zero-based. In other words, to set the thread affinity for the first processor, set the property to zero. + The value is zero-based. In other words, to set the thread affinity for the first processor, set the property to zero. The system schedules threads on their preferred processors whenever possible. @@ -397,9 +397,9 @@ is `true`, the system temporarily boosts the thread's priority whenever its associated process is taken out of the wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all existing threads as well as any threads subsequently created by the process. To restore normal behavior, set the property to `false`. + When is `true`, the system temporarily boosts the thread's priority whenever its associated process is taken out of the wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all existing threads as well as any threads subsequently created by the process. To restore normal behavior, set the property to `false`. - has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). + has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). > [!NOTE] > Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. @@ -481,7 +481,7 @@ to choose a value from the range specified in the property. + The priority level is not a single value, but rather a range of values. The operating system computes the thread's base priority by using the process's to choose a value from the range specified in the property. ]]> @@ -559,7 +559,7 @@ corresponds to the amount of time that the application has spent running in privileged mode, inside the operating system core. The property indicates the amount of time that the application has spent running code in user mode, outside the system core. + Windows uses several different protection mechanisms, and at the root of them all is the distinction between user mode and privileged mode. corresponds to the amount of time that the application has spent running in privileged mode, inside the operating system core. The property indicates the amount of time that the application has spent running code in user mode, outside the system core. User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. @@ -627,7 +627,7 @@ ## Remarks The processor affinity of a thread is the set of processors it has a relationship to. In other words, those it can be scheduled to run on. - represents each processor as a bit. Bit 0 represents processor one, bit 1 represents processor two, and so on. The following table shows a subset of the possible for a four-processor system. + represents each processor as a bit. Bit 0 represents processor one, bit 1 represents processor two, and so on. The following table shows a subset of the possible for a four-processor system. |Property value (in hexadecimal)|Valid processors| |---------------------------------------|----------------------| @@ -878,7 +878,7 @@ property value is valid only when the value is . Therefore, check the value before you get the property. + The property value is valid only when the value is . Therefore, check the value before you get the property. ]]> @@ -949,7 +949,7 @@ ## Remarks The property indicates the total amount of time that the system has taken the thread out of the wait state and given it priority on any processor. On a multiple processor system, this value would include time spent on each processor, if the thread used more than one processor. - The property is the sum of the and properties. + The property is the sum of the and properties. ]]> @@ -1021,7 +1021,7 @@ corresponds to the amount of time that the application has spent running in user mode, outside the operating system core. The corresponds to the amount of time that the application has spent running code in privileged mode, inside the system core. + Windows NT uses several different protection mechanisms, and at the root of them all is the distinction between user mode and privileged mode. corresponds to the amount of time that the application has spent running in user mode, outside the operating system core. The corresponds to the amount of time that the application has spent running code in privileged mode, inside the system core. User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. @@ -1083,7 +1083,7 @@ property is valid only when the is . Therefore, check the value before you get the property. + The property is valid only when the is . Therefore, check the value before you get the property. ]]> diff --git a/xml/System.Diagnostics/SourceFilter.xml b/xml/System.Diagnostics/SourceFilter.xml index 8590f04497a..5373fcdb5aa 100644 --- a/xml/System.Diagnostics/SourceFilter.xml +++ b/xml/System.Diagnostics/SourceFilter.xml @@ -59,7 +59,7 @@ This class filters events based on a specific trace source set by the user. - overrides the method and defines a property that specifies the name of the trace source to be traced by the listener. + overrides the method and defines a property that specifies the name of the trace source to be traced by the listener. > [!NOTE] > This filter is provided because multiple trace sources can simultaneously use the same trace listener. @@ -116,7 +116,7 @@ ## Examples - The following code example calls the method using two different source filters, one with a fictitious name, the other with the name of the current trace source. In the first case, the trace is not written to the console; in the second case, the trace is written. This code example is part of a larger example provided for the class. + The following code example calls the method using two different source filters, one with a fictitious name, the other with the name of the current trace source. In the first case, the trace is not written to the console; in the second case, the trace is written. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet28"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet28"::: @@ -259,7 +259,7 @@ identifies the trace source for which to write trace information. Trace information will not be written for other trace sources. The name of the trace source is the `name` parameter from the constructor for the . + identifies the trace source for which to write trace information. Trace information will not be written for other trace sources. The name of the trace source is the `name` parameter from the constructor for the . ]]> diff --git a/xml/System.Diagnostics/SourceSwitch.xml b/xml/System.Diagnostics/SourceSwitch.xml index 1697fbac5f8..23193bc5870 100644 --- a/xml/System.Diagnostics/SourceSwitch.xml +++ b/xml/System.Diagnostics/SourceSwitch.xml @@ -67,7 +67,7 @@ ``` - The switch is used to check whether a trace should be propagated or ignored. Each trace method calls the method before calling the listeners. If the method returns `false`, the trace is ignored and the trace method exits. If the method returns `true`, the trace is passed to the listeners. + The switch is used to check whether a trace should be propagated or ignored. Each trace method calls the method before calling the listeners. If the method returns `false`, the trace is ignored and the trace method exits. If the method returns `true`, the trace is passed to the listeners. ]]> @@ -319,7 +319,7 @@ To set the level of your in a .NET Framew method converts the new value of the property to the integer representation of the matching field in the enumeration, and then uses this integer to set the property. + The method converts the new value of the property to the integer representation of the matching field in the enumeration, and then uses this integer to set the property. ]]> diff --git a/xml/System.Diagnostics/StackFrame.xml b/xml/System.Diagnostics/StackFrame.xml index 97d0b105c44..e3976f8fb6c 100644 --- a/xml/System.Diagnostics/StackFrame.xml +++ b/xml/System.Diagnostics/StackFrame.xml @@ -189,7 +189,7 @@ constructor. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet3"::: @@ -249,7 +249,7 @@ constructor. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet2"::: @@ -315,7 +315,7 @@ ## Examples - The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet5"::: @@ -377,7 +377,7 @@ constructor. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet4"::: @@ -445,7 +445,7 @@ ## Examples - The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the constructor. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet6"::: @@ -505,7 +505,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet7"::: @@ -565,7 +565,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet7"::: @@ -632,7 +632,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet7"::: @@ -692,7 +692,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet7"::: @@ -764,12 +764,12 @@ property of the object that is returned by identifies the base class, not the derived class. + The method that is currently executing may be inherited from a base class, although it is called in a derived class. In this case, the property of the object that is returned by identifies the base class, not the derived class. ## Examples - The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/GetMethod/stacktracesample3.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/GetMethod/stacktracesample3.vb" id="Snippet6"::: @@ -822,7 +822,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet7"::: @@ -935,7 +935,7 @@ method. This code example is part of a larger example provided for the class. + The following example demonstrates the use of the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/StackFrame/Overview/source.vb" id="Snippet3"::: diff --git a/xml/System.Diagnostics/StackTrace.xml b/xml/System.Diagnostics/StackTrace.xml index 1e34017e5ec..0df52b7b78a 100644 --- a/xml/System.Diagnostics/StackTrace.xml +++ b/xml/System.Diagnostics/StackTrace.xml @@ -875,9 +875,9 @@ ## Remarks Use the returned array to enumerate and examine function calls in the . The length of the returned array is equal to the property value. - The array elements are in reverse chronological order. The at array index 0 represents the most recent function call in the stack trace and the last frame pushed onto the call stack. The at array index minus 1 represents the oldest function call in the stack trace and the first frame pushed onto the call stack. + The array elements are in reverse chronological order. The at array index 0 represents the most recent function call in the stack trace and the last frame pushed onto the call stack. The at array index minus 1 represents the oldest function call in the stack trace and the first frame pushed onto the call stack. - Use the method to obtain all stack frames in a stack trace; use the method to obtain a specific stack frame in a stack trace. The indexes are ordered alike by the two methods. For example, the at index 0 in the array returned by is equivalent to the returned by with an input index of 0. + Use the method to obtain all stack frames in a stack trace; use the method to obtain a specific stack frame in a stack trace. The indexes are ordered alike by the two methods. For example, the at index 0 in the array returned by is equivalent to the returned by with an input index of 0. diff --git a/xml/System.Diagnostics/Stopwatch.xml b/xml/System.Diagnostics/Stopwatch.xml index 74019fde41d..0385c255eb0 100644 --- a/xml/System.Diagnostics/Stopwatch.xml +++ b/xml/System.Diagnostics/Stopwatch.xml @@ -69,18 +69,18 @@ instance can measure elapsed time for one interval, or the total of elapsed time across multiple intervals. In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + A instance can measure elapsed time for one interval, or the total of elapsed time across multiple intervals. In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. - A instance is either running or stopped; use to determine the current state of a . Use to begin measuring elapsed time; use to stop measuring elapsed time. Query the elapsed time value through the properties , , or . You can query the elapsed time properties while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. + A instance is either running or stopped; use to determine the current state of a . Use to begin measuring elapsed time; use to stop measuring elapsed time. Query the elapsed time value through the properties , , or . You can query the elapsed time properties while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. - By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. + By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. The measures elapsed time by counting timer ticks in the underlying timer mechanism. If the installed hardware and operating system support a high-resolution performance counter, then the class uses that counter to measure elapsed time. Otherwise, the class uses the system timer to measure elapsed time. Use the and fields to determine the precision and resolution of the timing implementation. - The class assists the manipulation of timing-related performance counters within managed code. Specifically, the field and method can be used in place of the unmanaged Windows APIs `QueryPerformanceFrequency` and `QueryPerformanceCounter`. + The class assists the manipulation of timing-related performance counters within managed code. Specifically, the field and method can be used in place of the unmanaged Windows APIs `QueryPerformanceFrequency` and `QueryPerformanceCounter`. > [!NOTE] -> On a multiprocessor computer, it does not matter which processor the thread runs on. However, because of bugs in the BIOS or the Hardware Abstraction Layer (HAL), you can get different timing results on different processors. To specify processor affinity for a thread, use the method. +> On a multiprocessor computer, it does not matter which processor the thread runs on. However, because of bugs in the BIOS or the Hardware Abstraction Layer (HAL), you can get different timing results on different processors. To specify processor affinity for a thread, use the method. @@ -146,7 +146,7 @@ ## Remarks The returned instance is stopped, and the elapsed time property of the instance is zero. - Use the method to begin measuring elapsed time with the new instance. Use the method to initialize a new instance and immediately start it. + Use the method to begin measuring elapsed time with the new instance. Use the method to initialize a new instance and immediately start it. @@ -209,13 +209,13 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. Use the property to retrieve the elapsed time value using methods and properties. For example, you can format the returned instance into a text representation, or pass it to another class that requires a parameter. - You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. + You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. - By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. + By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. @@ -280,11 +280,11 @@ or properties. + This property represents elapsed time rounded down to the nearest whole millisecond value. For higher precision measurements, use the or properties. - You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. + You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. - By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. + By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. @@ -354,14 +354,14 @@ timer can measure. Use the field to convert the value into a number of seconds. + This property represents the number of elapsed ticks in the underlying timer mechanism. A tick is the smallest unit of time that the timer can measure. Use the field to convert the value into a number of seconds. - You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. + You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. - By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. + By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. > [!NOTE] -> ticks are different from . Each tick in the value represents one 100-nanosecond interval. Each tick in the value represents the time interval equal to 1 second divided by the . +> ticks are different from . Each tick in the value represents one 100-nanosecond interval. Each tick in the value represents the time interval equal to 1 second divided by the . @@ -571,12 +571,12 @@ class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. + If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. ## Examples - The following example illustrates the use of the method to update a performance counter. + The following example illustrates the use of the method to update a performance counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/NextValue/elapsedtime.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/NextValue/elapsedtime.vb" id="Snippet2"::: @@ -703,7 +703,7 @@ instance begins running with a call to or . The instance stops running with a call to or . + A instance begins running with a call to or . The instance stops running with a call to or . ]]> @@ -761,7 +761,7 @@ instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset. Use to stop the current interval measurement and retain the cumulative elapsed time value. Use to stop any interval measurement in progress and clear the elapsed time value. + A instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset. Use to stop the current interval measurement and retain the cumulative elapsed time value. Use to stop any interval measurement in progress and clear the elapsed time value. ]]> @@ -818,7 +818,7 @@ instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset or restarted. Use to stop the current interval measurement and retain the cumulative elapsed time value. Use to stop any interval measurement in progress and clear the elapsed time value. Use to stop current interval measurement and start a new interval measurement. + A instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset or restarted. Use to stop the current interval measurement and retain the cumulative elapsed time value. Use to stop any interval measurement in progress and clear the elapsed time value. Use to stop current interval measurement and start a new interval measurement. ]]> @@ -872,16 +872,16 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. Once started, a timer measures the current interval, in elapsed timer ticks, until the instance is stopped or reset. Starting a that is already running does not change the timer state or reset the elapsed time properties. - When a instance measures more than one interval, the method resumes measuring time from the current elapsed time value. A instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset. Use the method before calling to clear the cumulative elapsed time in a instance. Use the method to and the with a single command. + When a instance measures more than one interval, the method resumes measuring time from the current elapsed time value. A instance calculates and retains the cumulative elapsed time across multiple time intervals, until the instance is reset. Use the method before calling to clear the cumulative elapsed time in a instance. Use the method to and the with a single command. ## Examples - The following example demonstrates how to use the method to start a timer that measures the execution time of an application. + The following example demonstrates how to use the method to start a timer that measures the execution time of an application. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Stopwatch/Overview/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Stopwatch/Overview/source1.vb" id="Snippet1"::: @@ -943,7 +943,7 @@ constructor and then calling on the new instance. + This method is equivalent to calling the constructor and then calling on the new instance. @@ -1009,16 +1009,16 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. - The method ends the current time interval measurement. Stopping a that is not running does not change the timer state or reset the elapsed time properties. + The method ends the current time interval measurement. Stopping a that is not running does not change the timer state or reset the elapsed time properties. - When a instance measures more than one interval, the method is equivalent to pausing the elapsed time measurement. A subsequent call to resumes measuring time from the current elapsed time value. Use the method to clear the cumulative elapsed time in a instance. + When a instance measures more than one interval, the method is equivalent to pausing the elapsed time measurement. A subsequent call to resumes measuring time from the current elapsed time value. Use the method to clear the cumulative elapsed time in a instance. ## Examples - The following example demonstrates how to use the method to stop a timer that measures the execution time of an application. + The following example demonstrates how to use the method to stop a timer that measures the execution time of an application. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Stopwatch/Overview/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Stopwatch/Overview/source1.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/Switch.xml b/xml/System.Diagnostics/Switch.xml index 820465b1804..9c4408e2bad 100644 --- a/xml/System.Diagnostics/Switch.xml +++ b/xml/System.Diagnostics/Switch.xml @@ -78,7 +78,7 @@ ``` - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: @@ -90,7 +90,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Switch/Overview/source.vb" id="Snippet1"::: - The following example creates the new switch. The code implements a `Level` property to set the value of the new switch. `Level` calls the protected property that assigns the value to the new switch. This example also implements two assessor properties to get the assigned value of the switch. + The following example creates the new switch. The code implements a `Level` property to set the value of the new switch. `Level` calls the protected property that assigns the value to the new switch. This example also implements two assessor properties to get the assigned value of the switch. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Switch/Overview/source.vb" id="Snippet2"::: @@ -268,7 +268,7 @@ property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. + The `displayName` parameter is used to set the value of the property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. ]]> @@ -322,7 +322,7 @@ property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. @@ -408,7 +408,7 @@ constructor. + This property should indicate the function of the switch; for example, "Enables tracing for a directory watcher component." The value is set by the `descriptor` parameter in the constructor. ]]> @@ -469,7 +469,7 @@ object, the finds initial switch settings. For more information, see the constructor and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches) in the Visual Studio documentation. + When you create a new object, the finds initial switch settings. For more information, see the constructor and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches) in the Visual Studio documentation. @@ -542,12 +542,12 @@ method returns `null`. If a switch is added in a configuration file and custom attributes are specified that are not included in the string array returned by , a is thrown when the switch is loaded. + The default implementation for the method returns `null`. If a switch is added in a configuration file and custom attributes are specified that are not included in the string array returned by , a is thrown when the switch is loaded. ## Examples - The following code sample shows an override of the method for a custom switch. + The following code sample shows an override of the method for a custom switch. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet34"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet34"::: @@ -636,7 +636,7 @@ is invoked the first time a switch reads the value from the configuration file and is invoked again each time the switch's value is changed. + is invoked the first time a switch reads the value from the configuration file and is invoked again each time the switch's value is changed. ]]> @@ -816,7 +816,7 @@ method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. + The method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. ]]> diff --git a/xml/System.Diagnostics/SwitchAttribute.xml b/xml/System.Diagnostics/SwitchAttribute.xml index cde2262de97..1ae9d14a4ef 100644 --- a/xml/System.Diagnostics/SwitchAttribute.xml +++ b/xml/System.Diagnostics/SwitchAttribute.xml @@ -123,7 +123,7 @@ ## Examples - The following code example shows the use of the constructor to create a switch attribute. This code example is part of a larger example provided for the class. + The following code example shows the use of the constructor to create a switch attribute. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet2"::: @@ -184,7 +184,7 @@ method to identify the switches used in an assembly. This code example is part of a larger example provided for the class. + The following code example shows the use of the method to identify the switches used in an assembly. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: diff --git a/xml/System.Diagnostics/SwitchLevelAttribute.xml b/xml/System.Diagnostics/SwitchLevelAttribute.xml index 3080493b95e..17d45f854e8 100644 --- a/xml/System.Diagnostics/SwitchLevelAttribute.xml +++ b/xml/System.Diagnostics/SwitchLevelAttribute.xml @@ -160,7 +160,7 @@ class is . + The level property of a switch is not necessarily named `Level`; for example, the level property of the class is . diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index 01e2a393baa..525ad756c9c 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -59,9 +59,9 @@ The class provides the property to get or set the text writer that receives the tracing or debugging output. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - This class also provides methods to the so that it no longer receives tracing or debugging output, to the output buffer for the , and to a message to the . + This class also provides methods to the so that it no longer receives tracing or debugging output, to the output buffer for the , and to a message to the . You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -90,7 +90,7 @@ > If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. ## Examples - The following example implements an instance of the class that uses a called `myOutputWriter` to write to a file named `TestFile.txt`. First the example creates a file for output. Then it creates the for the first text writer, assigns it the output file, and adds it to the . Then, the code outputs one line of text to the file. Finally, the example flushes the output buffer. + The following example implements an instance of the class that uses a called `myOutputWriter` to write to a file named `TestFile.txt`. First the example creates a file for output. Then it creates the for the first text writer, assigns it the output file, and adds it to the . Then, the code outputs one line of text to the file. Finally, the example flushes the output buffer. After running this sample, you can open the `TestFile.txt` file to see the output. @@ -237,7 +237,7 @@ ## Examples - The following code example creates a using the constructor and adds it to the . The example then writes two messages to this , and writes a message to all objects in the . Finally, it flushes and closes the . + The following code example creates a using the constructor and adds it to the . The example then writes two messages to this , and writes a message to all objects in the . Finally, it flushes and closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstream.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstream.vb" id="Snippet1"::: @@ -305,7 +305,7 @@ ## Examples - The following code example creates a using the constructor. The example creates a , then references the when it creates the , which it then adds to the . The example writes a message to all objects in the , then closes this . + The following code example creates a using the constructor. The example creates a , then references the when it creates the , which it then adds to the . The example writes a message to all objects in the , then closes this . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/source.vb" id="Snippet1"::: @@ -379,7 +379,7 @@ ## Examples - The following code example creates a using the constructor, then adds it to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . + The following code example creates a using the constructor, then adds it to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstring.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstring.vb" id="Snippet3"::: @@ -457,7 +457,7 @@ ## Examples - The following code example creates a using the constructor and adds it to the . The example then writes two messages to this and writes a message to all objects in the . Finally, it flushes and closes the . + The following code example creates a using the constructor and adds it to the . The example then writes two messages to this and writes a message to all objects in the . Finally, it flushes and closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstreamname.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstreamname.vb" id="Snippet2"::: @@ -530,7 +530,7 @@ using the constructor. The example creates a , then references the when it creates the , which it then adds to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . + The following code example creates a using the constructor. The example creates a , then references the when it creates the , which it then adds to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconwritername.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconwritername.vb" id="Snippet5"::: @@ -606,7 +606,7 @@ ## Examples - The following code example creates a using the constructor, then adds it to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . + The following code example creates a using the constructor, then adds it to the . The example writes two messages to this , then writes a message to all objects in the . Finally, it flushes and closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstringname.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/twtlconstringname.vb" id="Snippet4"::: @@ -668,7 +668,7 @@ or method after calling automatically reopens the stream. + Calling a or method after calling automatically reopens the stream. @@ -739,7 +739,7 @@ method of the class to release the managed resources of a object. + Use the method of the class to release the managed resources of a object. ]]> @@ -990,7 +990,7 @@ that writes to the console screen. Then the code adds the new trace listener to the in the trace class. + The following example creates a that writes to the console screen. Then the code adds the new trace listener to the in the trace class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/Writer/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/Writer/source.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index f5a69563d44..a3eb723b462 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -58,26 +58,26 @@ ## Remarks You can use the properties and methods in the class to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system. - This class provides methods to display an dialog box, and to emit an assertion that will always . This class provides write methods in the following variations: + This class provides methods to display an dialog box, and to emit an assertion that will always . This class provides write methods in the following variations: -- -- -- -- +- +- +- +- The and classes provide means to dynamically control the tracing output. In .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in a .NET Framework app, see the class and [How to: Create, Initialize, and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). - You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the class. + You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the class. > [!NOTE] -> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. +> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. > [!NOTE] > If you add trace listeners to partially trusted code, you will get a exception, because adding trace listeners requires permission. To trace partially trusted code that is running in a sandbox in Visual Studio, do not add trace listeners. Instead, view the and messages in the **Output** window. - The class provides properties to get or set the level of and the , and whether to after each write. + The class provides properties to get or set the level of and the , and whether to after each write. -In .NET Framework apps, you can set the and for by editing the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: +In .NET Framework apps, you can set the and for by editing the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -97,7 +97,7 @@ In .NET Framework apps, you can set the is not supported by the C++ compiler. To provide equivalent functionality, you must enclose calls to the methods of in an `#if defined(TRACE) ... #endif` block, and add the `/DTRACE` option to the compiler command line or add `#define TRACE` to the file. ## Examples - The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](/dotnet/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code). + The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](/dotnet/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code). :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Overview/source.vb" id="Snippet1"::: @@ -190,14 +190,14 @@ In .NET Framework apps, you can set the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -214,7 +214,7 @@ For .NET Framework apps, you can change the behavior of the to verify the index value is valid. If it is not valid, the outputs the call stack. + The following example creates an index for an array. Then some action is performed that sets the value of the index. Next the code calls to verify the index value is valid. If it is not valid, the outputs the call stack. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Assert/source.vb" id="Snippet1"::: @@ -302,14 +302,14 @@ For .NET Framework apps, you can change the behavior of the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -326,7 +326,7 @@ For .NET Framework apps, you can change the behavior of the outputs a message. + The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Assert/source1.vb" id="Snippet1"::: @@ -407,14 +407,14 @@ For .NET Framework apps, you can change the behavior of the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user-interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: @@ -431,7 +431,7 @@ For .NET Framework apps, you can change the behavior of the outputs a message. + The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Assert/source2.vb" id="Snippet1"::: @@ -494,9 +494,9 @@ For .NET Framework apps, you can change the behavior of the or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. - To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -569,7 +569,7 @@ For .NET Framework apps, you can change the behavior of the . - Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. @@ -717,22 +717,22 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. + The default behavior for the default trace listener is to output the `message` parameter to a message box when the application runs in user-interface mode, and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can customize this behavior by adding a to, or by removing one from, the collection. + You can customize this behavior by adding a to, or by removing one from, the collection. ## Examples - The following example uses the method to print a message during exception handling. + The following example uses the method to print a message during exception handling. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Fail/source.vb" id="Snippet1"::: - You can also use the method in a switch statement. + You can also use the method in a switch statement. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Fail/source.vb" id="Snippet2"::: @@ -808,22 +808,22 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. + The default behavior is for the default trace listener to output the `message` parameter and the `detailedMessage` parameter to a message box when the application runs in user-interface mode, and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can customize this behavior by adding a to, or by removing one from, the collection. + You can customize this behavior by adding a to, or by removing one from, the collection. ## Examples - The following example uses the method to print a message during exception handling. + The following example uses the method to print a message during exception handling. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Fail/source1.vb" id="Snippet1"::: - You can also use the method in a switch statement. + You can also use the method in a switch statement. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Fail/source1.vb" id="Snippet2"::: @@ -889,7 +889,7 @@ For .NET Framework apps, you can change the behavior of the or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. @@ -1025,7 +1025,7 @@ End of list of errors property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. + The property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. @@ -1106,7 +1106,7 @@ End of list of errors This property is stored on per-thread/per-request basis. - To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -1178,15 +1178,15 @@ End of list of errors class. If you want to remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the class. + The listeners produce formatted output from the trace output. By default, the collection contains an instance of the class. If you want to remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the class. > [!NOTE] -> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. +> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. ## Examples - The following example creates a that outputs to the console screen. The code then adds the new listener to the . + The following example creates a that outputs to the console screen. The code then adds the new listener to the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Listeners/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Listeners/source.vb" id="Snippet1"::: @@ -1245,7 +1245,7 @@ End of list of errors method to update the trace configuration data. + Trace configuration data is captured when the application is started. If the configuration data is changed after the application is started, call the method to update the trace configuration data. ]]> @@ -1341,7 +1341,7 @@ End of list of errors calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. + calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. ]]> @@ -1427,7 +1427,7 @@ End of list of errors calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. ]]> @@ -1503,7 +1503,7 @@ End of list of errors calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. + calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. ]]> @@ -1589,7 +1589,7 @@ End of list of errors calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. ]]> @@ -1665,7 +1665,7 @@ End of list of errors calls the `TraceEvent` method for each trace listener with the trace event type , passing the informative message as the message string. + calls the `TraceEvent` method for each trace listener with the trace event type , passing the informative message as the message string. ]]> @@ -1751,7 +1751,7 @@ End of list of errors calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. ]]> @@ -1881,9 +1881,9 @@ End of list of errors . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. + The global lock is always used if the trace listener is not thread safe, regardless of the value of . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. - To set the for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: + To set the for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: ```xml @@ -1963,19 +1963,19 @@ End of list of errors ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. > [!NOTE] > ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first name of the `value` parameter to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first name of the `value` parameter to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. @@ -2049,19 +2049,19 @@ End of list of errors ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. > [!NOTE] > ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. @@ -2139,19 +2139,19 @@ End of list of errors The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. > [!NOTE] > ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2229,19 +2229,19 @@ End of list of errors The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. > [!NOTE] > ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2328,14 +2328,14 @@ End of list of errors ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. @@ -2428,14 +2428,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2532,14 +2532,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2636,14 +2636,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2743,14 +2743,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. @@ -2824,14 +2824,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2909,14 +2909,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -2994,14 +2994,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. @@ -3088,14 +3088,14 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. @@ -3188,14 +3188,14 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -3292,14 +3292,14 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. @@ -3396,14 +3396,14 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. ## Examples The following example creates a named `generalSwitch`. This switch is set outside the code sample. - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. diff --git a/xml/System.Diagnostics/TraceEventCache.xml b/xml/System.Diagnostics/TraceEventCache.xml index 1f183e41c85..097552d2470 100644 --- a/xml/System.Diagnostics/TraceEventCache.xml +++ b/xml/System.Diagnostics/TraceEventCache.xml @@ -59,7 +59,7 @@ > [!NOTE] > The class, designed as a performance optimization for trace listener calls, is of interest only to developers creating custom trace listeners. - The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. + The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. ]]> @@ -145,7 +145,7 @@ property gets the call stack from the property of the class. The property value lists method calls in reverse chronological order. That is, the most recent method call is described first. One line of stack trace information is listed for each method call on the stack. For more information, see . + The property gets the call stack from the property of the class. The property value lists method calls in reverse chronological order. That is, the most recent method call is described first. One line of stack trace information is listed for each method call on the stack. For more information, see . ]]> @@ -242,7 +242,7 @@ class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack + The correlation data is stored as an object in the call context with the name "System.Diagnostics.Trace.CorrelationManagerSlot". The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack ]]> @@ -395,7 +395,7 @@ method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . + The get accessor calls the method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . ]]> diff --git a/xml/System.Diagnostics/TraceEventType.xml b/xml/System.Diagnostics/TraceEventType.xml index 7932b9e1803..f4be3c0bc50 100644 --- a/xml/System.Diagnostics/TraceEventType.xml +++ b/xml/System.Diagnostics/TraceEventType.xml @@ -45,11 +45,11 @@ Identifies the type of event that has caused the trace. - is used to identify the event that caused a trace in calls to the methods. - + is used to identify the event that caused a trace in calls to the methods. + ]]> diff --git a/xml/System.Diagnostics/TraceFilter.xml b/xml/System.Diagnostics/TraceFilter.xml index 4703ec685a6..c22baf7eee5 100644 --- a/xml/System.Diagnostics/TraceFilter.xml +++ b/xml/System.Diagnostics/TraceFilter.xml @@ -51,7 +51,7 @@ ## Remarks Trace filters can be used by trace listeners to provide an extra layer of filtering beyond that provided by trace switches. The trace filter for a trace listener can be found in the listener's property. Trace switches determine if a trace is to be sent to the trace listeners. Trace filters allow the individual trace listeners to determine whether or not the trace is to be written to the associated output medium. For example, as determined by each trace filter, a trace may be written to the console by a , but not to the event log by a . - Filters that inherit from the class can be used by trace listeners that inherit from the class to perform filtering of events being traced. contains a single method, , which takes event data and returns a flag indicating whether the event should be traced. + Filters that inherit from the class can be used by trace listeners that inherit from the class to perform filtering of events being traced. contains a single method, , which takes event data and returns a flag indicating whether the event should be traced. ]]> @@ -178,7 +178,7 @@ method to indicate tracing should occur when the trace event type of the event is equal to . + The following code example shows how to override the method to indicate tracing should occur when the trace event type of the event is equal to . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceFilter/ShouldTrace/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceFilter/ShouldTrace/source.vb" id="Snippet2"::: diff --git a/xml/System.Diagnostics/TraceListener.xml b/xml/System.Diagnostics/TraceListener.xml index 80bac8a79d6..0db03c6337b 100644 --- a/xml/System.Diagnostics/TraceListener.xml +++ b/xml/System.Diagnostics/TraceListener.xml @@ -274,7 +274,7 @@ class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". + Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". ```xml @@ -287,7 +287,7 @@ ``` - Unreferenced custom attributes are not enumerated. For more information, see the method. + Unreferenced custom attributes are not enumerated. For more information, see the method. ]]> @@ -406,7 +406,7 @@ allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> @@ -461,7 +461,7 @@ method and the method, if it has been overridden. `Dispose` invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by the public method and the method, if it has been overridden. `Dispose` invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -800,12 +800,12 @@ returns `null`. + The default implementation for returns `null`. ## Examples - The following code sample shows an override of the method for a custom trace listener. + The following code sample shows an override of the method for a custom trace listener. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceListener/GetSupportedAttributes/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceListener/GetSupportedAttributes/program.vb" id="Snippet1"::: @@ -988,7 +988,7 @@ is used to determine whether to use a global lock when writing to the listener. If the value of is `false`, the global lock is used regardless of the value of . The global lock is not used only if the value of is `true` and the value of is `false`. The default behavior is to use the global lock whenever writing to the listener. + The value of is used to determine whether to use a global lock when writing to the listener. If the value of is `false`, the global lock is used regardless of the value of . The global lock is not used only if the value of is `true` and the value of is `false`. The default behavior is to use the global lock whenever writing to the listener. ]]> @@ -1116,7 +1116,7 @@ method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. + **Note** The method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. ]]> @@ -1583,7 +1583,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. ]]> @@ -1657,7 +1657,7 @@ - The `Write` and `WriteLine` methods of the , , and classes. -- The and methods of the class when they are not overridden in a derived class. +- The and methods of the class when they are not overridden in a derived class. @@ -1743,7 +1743,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The method is used for the correlation of related traces. The method calls the method to process the call, with the eventType level set to and the `relatedActivityId` as a string appended to the message. + The method is used for the correlation of related traces. The method calls the method to process the call, with the eventType level set to and the `relatedActivityId` as a string appended to the message. ]]> @@ -2033,7 +2033,7 @@ property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. + This method writes the indent and resets the property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. ]]> diff --git a/xml/System.Diagnostics/TraceListenerCollection.xml b/xml/System.Diagnostics/TraceListenerCollection.xml index 2fd6bef630c..bdc034b65c8 100644 --- a/xml/System.Diagnostics/TraceListenerCollection.xml +++ b/xml/System.Diagnostics/TraceListenerCollection.xml @@ -67,18 +67,18 @@ list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. + The list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. - This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. + This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. - The class provides the property for information about the list. It also provides the following methods: , , . + The class provides the property for information about the list. It also provides the following methods: , , . - This class also provides the following methods to modify the list: , , , and . The method copies a part of the list to an array. The method deletes the list member at a specified index number. + This class also provides the following methods to modify the list: , , , and . The method copies a part of the list to an array. The method deletes the list member at a specified index number. ## Examples - The following example creates a that writes to the console screen. The code then adds the new listener to the . + The following example creates a that writes to the console screen. The code then adds the new listener to the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Listeners/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Trace/Listeners/source.vb" id="Snippet1"::: @@ -141,7 +141,7 @@ that outputs to the console screen. The code then adds the new listener to the . + The following example creates a that outputs to the console screen. The code then adds the new listener to the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceListenerCollection/Add/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceListenerCollection/Add/source.vb" id="Snippet1"::: @@ -380,7 +380,7 @@ method can confirm the existence of a before you perform further operations. + The method can confirm the existence of a before you perform further operations. ]]> @@ -804,7 +804,7 @@ property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. + The property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. ]]> @@ -928,7 +928,7 @@ method will find the specific listener you name. + The `name` parameter is case-sensitive. That is, if two listeners exist with the names "Rname" and "rname", the method will find the specific listener you name. ]]> @@ -1057,7 +1057,7 @@ method of the class to copy all or part of the collection to an array. + Use the method of the class to copy all or part of the collection to an array. ]]> @@ -1220,7 +1220,7 @@ This member is an explicit interface member implementation. It can be used only method to add a new trace listener to the collection. + Use the method to add a new trace listener to the collection. ]]> @@ -1284,7 +1284,7 @@ This member is an explicit interface member implementation. It can be used only method of the class to determine whether the collection contains a specific object. + Use the method of the class to determine whether the collection contains a specific object. ]]> @@ -1341,7 +1341,7 @@ This member is an explicit interface member implementation. It can be used only method of the class to determine the index of a object in the collection. + Use the method of the class to determine the index of a object in the collection. ]]> @@ -1399,7 +1399,7 @@ This member is an explicit interface member implementation. It can be used only method of the class to insert a object into the collection. + Use the method of the class to insert a object into the collection. ]]> @@ -1626,7 +1626,7 @@ This member is an explicit interface member implementation. It can be used only method of the class to remove a from the collection. + Use the method of the class to remove a from the collection. ]]> diff --git a/xml/System.Diagnostics/TraceLogRetentionOption.xml b/xml/System.Diagnostics/TraceLogRetentionOption.xml index 7260aa69c8a..1eb82cc90f7 100644 --- a/xml/System.Diagnostics/TraceLogRetentionOption.xml +++ b/xml/System.Diagnostics/TraceLogRetentionOption.xml @@ -19,9 +19,9 @@ enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. + The enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. - You can set the and properties through the `maximumFileSize` and `maximumNumberOfFiles` custom attributes in the configuration file or by using the `maximumFileSize` or `maximumNumberOfFiles` parameters in the constructor. If the `maximumFileSize` or `maximumNumberOfFiles` attributes in the configuration file specify an out-of-range value, the properties are set to their default values. If you specify an out-of-range value in the `maximumFileSize` or `maximumNumberOfFiles` parameter when you call the constructor, an is thrown. + You can set the and properties through the `maximumFileSize` and `maximumNumberOfFiles` custom attributes in the configuration file or by using the `maximumFileSize` or `maximumNumberOfFiles` parameters in the constructor. If the `maximumFileSize` or `maximumNumberOfFiles` attributes in the configuration file specify an out-of-range value, the properties are set to their default values. If you specify an out-of-range value in the `maximumFileSize` or `maximumNumberOfFiles` parameter when you call the constructor, an is thrown. The following table shows the possible and default values for file size and file count that are associated with each trace log retention option. "N/A" indicates that the associated property is not checked for that value. diff --git a/xml/System.Diagnostics/TraceOptions.xml b/xml/System.Diagnostics/TraceOptions.xml index 73aadea3215..3fc5d9c8382 100644 --- a/xml/System.Diagnostics/TraceOptions.xml +++ b/xml/System.Diagnostics/TraceOptions.xml @@ -80,7 +80,7 @@ - The `Write` and `WriteLine` methods of the , , and classes. -- The and methods of the class when they are not overridden in a derived class. +- The and methods of the class when they are not overridden in a derived class. ## Examples The following code example shows the use of the enumeration to programmatically set the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index 240bc64fee5..a87926b6641 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -103,18 +103,18 @@ In .NET Framework apps, trace output from The preceding .NET Framework app configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source) and [\](/dotnet/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element). > [!NOTE] -> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. +> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. The class provides the means to dynamically control the tracing output. For .NET Framework apps, the preceding configuration file example shows how you can turn off tracing from a trace source and control the level at which tracing occurs. You can modify the value of the source switch without recompiling your application. For information on using the configuration file to set a switch, see and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). > [!NOTE] -> If you modify a configuration file while an application is executing, the application must be stopped and restarted or the method must be called before the new settings take effect. +> If you modify a configuration file while an application is executing, the application must be stopped and restarted or the method must be called before the new settings take effect. The enumeration is used to define the event type of the trace message. Trace filters use the to determine if a trace listener should produce the trace message. - The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. + The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. - The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. + The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. ```xml @@ -203,7 +203,7 @@ The preceding .NET Framework app configuration file example demonstrates removin ## Examples - The following code example shows the use of the constructor to create a new object. This code example is part of a larger example provided for the class. + The following code example shows the use of the constructor to create a new object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet9"::: @@ -316,7 +316,7 @@ The preceding .NET Framework app configuration file example demonstrates removin property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. The following is a sample of a trace source element specifying the custom attribute `SecondTraceSourceAttribute`: @@ -384,12 +384,12 @@ The preceding .NET Framework app configuration file example demonstrates removin method calls the method of each trace listener in the collection. + The method calls the method of each trace listener in the collection. ## Examples - The following code example shows how you can use the method to close all the listeners in the collection. This code example is part of a larger example provided for the class. + The following code example shows how you can use the method to close all the listeners in the collection. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet33"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet33"::: @@ -469,12 +469,12 @@ The preceding .NET Framework app configuration file example demonstrates removin method calls the method of each trace listener in the collection. + The method calls the method of each trace listener in the collection. ## Examples - The following code example shows how you can use the method to flush all the listeners in the collection. This code example is part of a larger example provided for the class. + The following code example shows how you can use the method to flush all the listeners in the collection. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet33"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet33"::: @@ -538,12 +538,12 @@ The preceding .NET Framework app configuration file example demonstrates removin returns `null`. + The default implementation for returns `null`. ## Examples - The following code example shows an override of the method to identify the custom attributes for the `MyTraceSource` class. + The following code example shows an override of the method to identify the custom attributes for the `MyTraceSource` class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet33"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet33"::: @@ -756,7 +756,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks The property allows the filtering of messages before the trace source calls the listeners. - The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the method of the to determine whether to proceed with the trace. If the call returns `true`, the listeners are called. + The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the method of the to determine whether to proceed with the trace. If the call returns `true`, the listeners are called. ]]> @@ -831,9 +831,9 @@ You can refer to the trace source by using the `name` attribute in the configura method, like the method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace. + The method, like the method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -841,7 +841,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Examples - The following code example shows the use of the method to filter and forward a trace message to the listeners. This code example is part of a larger example provided for the class. + The following code example shows the use of the method to filter and forward a trace message to the listeners. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet28"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet28"::: @@ -915,9 +915,9 @@ You can refer to the trace source by using the `name` attribute in the configura method, like the method, is intended for automated tools, but it also allows the attaching of additional objects, such as an exception instance and a stack trace, to the trace. + The method, like the method, is intended for automated tools, but it also allows the attaching of additional objects, such as an exception instance and a stack trace, to the trace. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -991,9 +991,9 @@ You can refer to the trace source by using the `name` attribute in the configura method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. + The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, and the event type. Additional trace content is dependent upon the listener's property value. @@ -1003,7 +1003,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Examples - The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. + The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet17"::: @@ -1070,9 +1070,9 @@ You can refer to the trace source by using the `name` attribute in the configura method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. + The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, the event type, and the message. Additional trace content is dependent upon the listener's property value. @@ -1082,7 +1082,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Examples - The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. + The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet18"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet18"::: @@ -1168,11 +1168,11 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks For more information about the `format` parameter, see [Composite Formatting](/dotnet/standard/base-types/composite-formatting). - The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. + The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. - The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. + The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -1180,7 +1180,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Examples - The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. + The following code example shows the use of the method to pass a trace event to the listeners. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet24"::: @@ -1272,9 +1272,9 @@ You can refer to the trace source by using the `name` attribute in the configura method provides an informational message intended to be read by users and not by tools. + The method provides an informational message intended to be read by users and not by tools. - calls the method, setting `eventType` to and passing the informative message as the message string. The method in turn calls the method of each trace listener. + calls the method, setting `eventType` to and passing the informative message as the message string. The method in turn calls the method of each trace listener. ]]> @@ -1357,9 +1357,9 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks For more information about the `format` parameter, see [Composite Formatting](/dotnet/standard/base-types/composite-formatting). - The method provides an informational message intended to be read by users and not by tools. + The method provides an informational message intended to be read by users and not by tools. - calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. + calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. ]]> @@ -1437,9 +1437,9 @@ You can refer to the trace source by using the `name` attribute in the configura method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. + The method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. - is intended to be used with the logical operations of a . The `relatedActivityId` parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities. + is intended to be used with the logical operations of a . The `relatedActivityId` parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities. ]]> diff --git a/xml/System.Diagnostics/TraceSwitch.xml b/xml/System.Diagnostics/TraceSwitch.xml index 036d4a85910..36c49f55766 100644 --- a/xml/System.Diagnostics/TraceSwitch.xml +++ b/xml/System.Diagnostics/TraceSwitch.xml @@ -60,7 +60,7 @@ class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . + You can use a trace switch to filter out messages based on their importance. The class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . You can create a in your code and set the level directly to instrument a specific section of code. @@ -76,7 +76,7 @@ In .NET Framework apps only, you can also set the level of a ``` - This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . + This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . > [!NOTE] > You can also use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. @@ -88,7 +88,7 @@ In .NET Framework apps only, you can also set the level of a of the new switch defaults to . -In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . +In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -105,7 +105,7 @@ In .NET Framework apps, the switch p > To improve performance, you can make members `static` in your class. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -211,13 +211,13 @@ You can also use text to specify the value for a switch. For example, `true` for This constructor sets the property of the new switch to . Or, for .NET Framework apps, the switch settings are obtained from the configuration file, if available. - The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . + The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . > [!NOTE] > To improve performance, you can make members `static` in your class. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -292,7 +292,7 @@ This constructor sets the property o property, the `description` parameter is use to set the value of the property, and the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. See the constructor for more information and a code example. + The `displayName` parameter is used to set the value of the property, the `description` parameter is use to set the value of the property, and the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. See the constructor for more information and a code example. ]]> @@ -362,10 +362,10 @@ You can also use text to specify the value for a switch. For example, `true` for The default value of the property is . Or, for .NET Framework apps, the level is obtained from the configuration file, if available. - Setting this property updates the , , , and properties to reflect the new value. + Setting this property updates the , , , and properties to reflect the new value. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Level/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Level/source.vb" id="Snippet1"::: @@ -425,7 +425,7 @@ The default value of the property is method is used by the .NET framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the enumeration and the switch is set to a defined value. + The method is used by the .NET framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the enumeration and the switch is set to a defined value. If you attempt in your code to set the property to a value that is not defined by the enumeration, an exception is thrown. @@ -534,12 +534,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -598,12 +598,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/TraceInfo/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/TraceInfo/source.vb" id="Snippet1"::: @@ -662,7 +662,7 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. @@ -726,12 +726,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/TraceWarning/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/TraceWarning/source.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml b/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml index baa33d8e411..b0babbdae7f 100644 --- a/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml +++ b/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml @@ -20,7 +20,7 @@ methods. It can also be used to pass XML data to the methods. + This class is used by the methods. It can also be used to pass XML data to the methods. > [!NOTE] > The user-provided data is not checked for schema validity. @@ -68,7 +68,7 @@ ## Examples - The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet11"::: diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index 94be22816b8..8fccdf4758d 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -62,13 +62,13 @@ You can create an in your code. ``` - The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. > [!NOTE] > If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. > [!NOTE] -> Listener methods are intended to be called by methods of the , , and classes. The listener methods are not intended to be called directly from application code. The listener is primarily intended for use by the class. The and methods can be called by the and classes, and default values are provided for the XML elements that and do not supply values for. +> Listener methods are intended to be called by methods of the , , and classes. The listener methods are not intended to be called directly from application code. The listener is primarily intended for use by the class. The and methods can be called by the and classes, and default values are provided for the XML elements that and do not supply values for. The following table describes the elements and attributes of the XML output. @@ -77,8 +77,8 @@ You can create an in your code. |`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| |`Computer`|None|Always present.|The value of the property.| |`Correlation`|`ActivityID`|Always present|If not specified, the default is an empty GUID.| -||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the Trace method call.|The `relatedActivityId` parameter of the method.| -|`DataItem`|None|Depends on the `data` parameter of the method.|This element can contain an array of elements or one element, so the values are written as a set of `DataItem` nodes under the `TraceData` element.

The data output uses the `ToString` method of the passed-in data objects.| +||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the Trace method call.|The `relatedActivityId` parameter of the method.| +|`DataItem`|None|Depends on the `data` parameter of the method.|This element can contain an array of elements or one element, so the values are written as a set of `DataItem` nodes under the `TraceData` element.

The data output uses the `ToString` method of the passed-in data objects.| |`EventID`|None|Always present.|Parameter input (`id`).| |`Execution`|`ProcessName`|Always present.|From the .| ||`ProcessID`|Always present.|From the .| @@ -92,7 +92,7 @@ You can create an in your code. |`TimeStamp`|None|Depends on the presence of the flag in the property.|From the .| |`Type`|None|Always present.|Always the value 3.| - The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. + The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. |Escaped character|Value| |-----------------------|-----------| @@ -245,7 +245,7 @@ You can create an in your code. class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + This constructor initializes a new instance of the class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. @@ -303,7 +303,7 @@ You can create an in your code. property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -361,7 +361,7 @@ You can create an in your code. property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -412,12 +412,12 @@ You can create an in your code. class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + This constructor initializes a new instance of the class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -503,7 +503,7 @@ You can create an in your code. instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. + The default behavior is to display the message and detailed message in a message box when the application is running in user-interface mode, and to the instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. ]]> @@ -794,7 +794,7 @@ You can create an in your code. method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. @@ -857,10 +857,10 @@ You can create an in your code. method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . + The method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . > [!IMPORTANT] -> The method is not intended to be called by application code. It is intended to be called by a object to emit the trace information for its method. +> The method is not intended to be called by application code. It is intended to be called by a object to emit the trace information for its method. ]]> @@ -905,7 +905,7 @@ You can create an in your code. method to include context information in the log output. + Use the method to include context information in the log output. ]]> @@ -950,7 +950,7 @@ You can create an in your code. method to include context information in the log output. + Use the method to include context information in the log output. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml index c5460d84ae6..7a3a529315d 100644 --- a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml @@ -145,9 +145,9 @@ properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . + When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . ]]> @@ -178,11 +178,11 @@ method. + The account lockout time is system dependent, and cannot be set by the Account Management API. To unlock the account, use the method. - It is possible that an account may not be locked out when the returns a non-null value. Applications should use the method to determine whether the account is locked out. + It is possible that an account may not be locked out when the returns a non-null value. Applications should use the method to determine whether the account is locked out. - As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. ]]> @@ -959,7 +959,7 @@ ctx.Dispose(); returns a non-null value. This method computes the correct store-specific lockout value to determine whether the account is locked out. + It is possible that an account may not be locked out when the returns a non-null value. This method computes the correct store-specific lockout value to determine whether the account is locked out. ]]> @@ -989,7 +989,7 @@ ctx.Dispose(); properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. ]]> @@ -1020,7 +1020,7 @@ ctx.Dispose(); properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. ]]> @@ -1051,7 +1051,7 @@ ctx.Dispose(); properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. + As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml index 9ad366331ca..755d97b519d 100644 --- a/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml @@ -49,7 +49,7 @@ method. + The computer principal account is not persisted when it is created. To persist the account, call the method. ]]> @@ -79,7 +79,7 @@ method. + The computer principal account is not persisted when it is created. To save the account, call the method. ]]> @@ -115,7 +115,7 @@ method. + The computer principal account is not persisted when it is created. To persist the account, call the method. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml index 841db332aa9..38431d19515 100644 --- a/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml @@ -71,7 +71,7 @@ method. + The group principal account is not persisted when it is created. To persist the account, call the method. ]]> @@ -103,7 +103,7 @@ method. + The group principal account is not persisted when it is created. To persist the account, call the method. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml b/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml index ca00171c4c1..f9563542b07 100644 --- a/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml +++ b/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml @@ -70,7 +70,7 @@ class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The is initialized to `null`. + The parameterless constructor initializes a new instance of the class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The is initialized to `null`. ]]> @@ -183,7 +183,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml b/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml index f8c1938d358..4a2adbbe6bc 100644 --- a/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml +++ b/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml @@ -183,7 +183,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PasswordException.xml b/xml/System.DirectoryServices.AccountManagement/PasswordException.xml index e876201cbc2..6866f2db7cf 100644 --- a/xml/System.DirectoryServices.AccountManagement/PasswordException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PasswordException.xml @@ -183,7 +183,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/Principal.xml b/xml/System.DirectoryServices.AccountManagement/Principal.xml index 16893baa762..c43686c71fc 100644 --- a/xml/System.DirectoryServices.AccountManagement/Principal.xml +++ b/xml/System.DirectoryServices.AccountManagement/Principal.xml @@ -697,7 +697,7 @@ method. + This overloaded method only returns the groups of which the principal is directly a member; no recursive searches are performed. Recursive search results are available for user principal objects. For more information, see the method. If the principal store is AD DS, the list of groups contains the user's primary group that is identified by the primary group ID attribute in the AD DS object. @@ -737,7 +737,7 @@ method. + This method returns only the groups of which the principal is directly a member; no recursive searches are performed. Recursive search results are available for user principal objects. For more information, see the method. The groups that are returned by this method may include groups from a different scope and store than the principal. For example, if the principal is an AD DS object that has a DN of "CN=SpecialGroups,DC=Fabrikam,DC=com, the returned set can contain groups that belong to the "CN=NormalGroups,DC=Fabrikam,DC=com. @@ -784,7 +784,7 @@ method. + This method returns only the groups of which the principal is directly a member; no recursive searches are performed. Recursive search results are available for user principal objects. For more information, see the method. The groups that are returned by this method may include groups from a different scope and store than the principal. For example, if the principal is an AD DS object that has a DN of "CN=SpecialGroups,DC=Fabrikam,DC=com, the returned set can contain groups that belong to the "CN=NormalGroups,DC=Fabrikam,DC=com. diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalCollection.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalCollection.xml index 02cde7859a6..395e40bf40e 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalCollection.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalCollection.xml @@ -53,11 +53,11 @@ Adds the specified principal to the end of the collection. - and , There are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. - + and , There are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. + ]]> @@ -96,15 +96,15 @@ A object. Adds the specified object to the end of the collection. - |`computer` already exists in the collection.| - + |`computer` already exists in the collection.| + ]]> @@ -143,15 +143,15 @@ A object. Adds the specified object to the end of the collection. - |`group` already exists in the collection.| - + |`group` already exists in the collection.| + ]]> @@ -189,15 +189,15 @@ A object. Adds the specified object to the end of the collection. - |`principal` already exists in the collection.| - + |`principal` already exists in the collection.| + ]]> @@ -236,15 +236,15 @@ A object. Adds the specified object to the end of the collection. - |`user` already exists in the collection.| - + |`user` already exists in the collection.| + ]]> @@ -283,18 +283,18 @@ A string that identifies the principal, in the format specified by . Searches for a object that matches the parameters, and adds it to the end of the collection. - |The principal matching these parameters already exists in the collection.| -||No principal matching the specified parameters was found.| -||More than one principal matches the specified parameters.| -||`identityType` is an empty string| - + |The principal matching these parameters already exists in the collection.| +||No principal matching the specified parameters was found.| +||More than one principal matches the specified parameters.| +||`identityType` is an empty string| + ]]> @@ -329,15 +329,15 @@ Removes all objects from the collection. - |If this method is called on the PrincipalCollection, the property cannot be cleared because one or more of the group's members have this group as their primary group.| - + |If this method is called on the PrincipalCollection, the property cannot be cleared because one or more of the group's members have this group as their primary group.| + ]]> @@ -350,11 +350,11 @@ Returns a value that indicates whether the specified is a member of the . The can be specified in the same manner as in the methods. - , and there are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. - + , and there are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. + ]]> @@ -546,16 +546,16 @@ if an object matching the / pair is in the collection; otherwise, . - |There are multiple principals matching these parameters.| -||The `identityType` parameter cannot be empty.| - + |There are multiple principals matching these parameters.| +||The `identityType` parameter cannot be empty.| + ]]> @@ -589,11 +589,11 @@ The position in into which the first principal object in the collection should be copied. Copies the objects from this into the specified array, starting at the specified position index in array. - is thrown. Further exceptions are thrown if the number of elements to copy is greater than the available space from `index` to the end of `array`, if `array` is `null`, or if `index` is less than 0. - + is thrown. Further exceptions are thrown if the number of elements to copy is greater than the available space from `index` to the end of `array`, if `array` is `null`, or if `index` is less than 0. + ]]> @@ -661,11 +661,11 @@ Returns an enumerator to iterate through the principals in the . An containing the principals in the . - has a single enumerator associated with it. Although multiple calls to return distinct objects, they share the same internal state. - + has a single enumerator associated with it. Although multiple calls to return distinct objects, they share the same internal state. + ]]> @@ -727,11 +727,11 @@ Removes the specified principal from the collection, and returns if the specified principal object was a member of the collection, and otherwise (in which case no operation is performed). - , and there are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. - + , and there are four overloads to this function, but they all do the same thing. The extra overloads are only implemented to improve usability, so that developers using IntelliSense see overloads that take a , , or object. Calling any one of the User, Group, or Computer overloads is exactly equivalent to calling the overload. + ]]> @@ -772,15 +772,15 @@ if the was a member of this ; otherwise, . - |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| - + |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| + ]]> @@ -821,15 +821,15 @@ if the was a member of this ; otherwise, . - |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| - + |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| + ]]> @@ -869,15 +869,15 @@ if the was a member of this ; otherwise, . - |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| - + |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| + ]]> @@ -918,15 +918,15 @@ if the was a member of this ; otherwise, . - |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| - + |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| + ]]> @@ -967,18 +967,18 @@ if the identified was a member of this ; otherwise, . - |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| -||No principal matching the specified parameters was found.| -||More than one principal matches the specified parameters. In theory, this should never happen, because throws an exception when there is an attempt to add duplicate principals to the collection. However, it is possible that another API created the duplicate.| -||`identityType` is an empty string.| - + |This method was called on the collection for a domain group, and the domain principal to be removed is a member of the group by virtue of its `primaryGroupId` attribute.| +||No principal matching the specified parameters was found.| +||More than one principal matches the specified parameters. In theory, this should never happen, because throws an exception when there is an attempt to add duplicate principals to the collection. However, it is possible that another API created the duplicate.| +||`identityType` is an empty string.| + ]]> @@ -1041,11 +1041,11 @@ The position in to which the first object should be copied to. Copies the objects from this into the specified array, starting at the specified position index in array. - is thrown. Further exceptions are thrown if the number of elements to copy is greater than the available space from `index` to the end of `array`, if `array` is `null`, or if `index` is less than 0. - + is thrown. Further exceptions are thrown if the number of elements to copy is greater than the available space from `index` to the end of `array`, if `array` is `null`, or if `index` is less than 0. + ]]> @@ -1209,11 +1209,11 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator to iterate through the principals in the . An containing the principals in the . - has a single enumerator associated with it. Although multiple calls to return distinct objects, they share the same internal state. - + has a single enumerator associated with it. Although multiple calls to return distinct objects, they share the same internal state. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml index 5076290a68b..1cecef01bec 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalContext.xml @@ -597,7 +597,7 @@ The `userName` argument in both overloads of this method must take the form *use method binds to the server specified in the constructor. If the `username` and `password` arguments are `null`, this method validates the default credentials for the current principal. + The method binds to the server specified in the constructor. If the `username` and `password` arguments are `null`, this method validates the default credentials for the current principal. The `userName` argument must take the form *userName* (for example, *mcampbell*) rather than *domain\username* or *username\@domain*. @@ -638,7 +638,7 @@ The `userName` argument must take the form *userName* (for example, *mcampbell*) method binds to the server specified in the constructor. If the `username` and `password` parameters are `null`, this method validates the default credentials for the current principal. + The method binds to the server specified in the constructor. If the `username` and `password` parameters are `null`, this method validates the default credentials for the current principal. The `userName` argument must take the form *username* (for example, *mcampbell*) rather than *domain\username* or *username\@domain*. diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml index 6abae347da8..28840ac4908 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml @@ -183,7 +183,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml index b32f41eea67..a7504d34e69 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml @@ -179,7 +179,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> @@ -257,7 +257,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml index ff091c4443d..cdcd6c198ba 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml @@ -33,7 +33,7 @@ class performs a query for domain principals. The application may override the default value by setting the property in the underlying object that is returned from the method. + The default page size of 256 KB is used when the class performs a query for domain principals. The application may override the default value by setting the property in the underlying object that is returned from the method. ]]> @@ -260,7 +260,7 @@ , this method returns that object. If there are multiple matches of the object, this method arbitrarily returns one of the matching principals. + If there is exactly one match of the object specified in the , this method returns that object. If there are multiple matches of the object, this method arbitrarily returns one of the matching principals. The object returned from this method matches the type of object contained in the property. The search is conducted in the context specified in the property. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. @@ -382,7 +382,7 @@ can also be an extended principal type that is defined by extending either , , or . The type of the derived class object that is passed to this property determines the type of object that is queried. The resulting query contains a logical AND of all the properties set on the specified principal object. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. For more information on the extended classes, see the [Principal Extensions](https://learn.microsoft.com/previous-versions/bb384372(v=vs.90)) overview topic. + The principal object contained in this property can be any type of object derived from the principal class: computer, user, or group. The can also be an extended principal type that is defined by extending either , , or . The type of the derived class object that is passed to this property determines the type of object that is queried. The resulting query contains a logical AND of all the properties set on the specified principal object. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. For more information on the extended classes, see the [Principal Extensions](https://learn.microsoft.com/previous-versions/bb384372(v=vs.90)) overview topic. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml index cec9173485a..7fe0c669138 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml @@ -179,7 +179,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> @@ -257,7 +257,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the private `errorCode` property is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the private `errorCode` property is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> @@ -299,7 +299,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, the private `errorCode` property is set to `errorCode`, and the private `serverName` property is set to `serverName`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, the private `errorCode` property is set to `errorCode`, and the private `serverName` property is set to `serverName`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. ]]> @@ -348,7 +348,7 @@ sets a with all the exception object data targeted for serialization. During deserialization, the exception object is reconstituted from the transmitted over the stream. + sets a with all the exception object data targeted for serialization. During deserialization, the exception object is reconstituted from the transmitted over the stream. For more information, see . diff --git a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml index 87b36b16a19..8802421b922 100644 --- a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml @@ -71,7 +71,7 @@ method. + The user principal account is not persisted when it is created. To save the account, call the method. @@ -135,7 +135,7 @@ ctx.Dispose(); method. + The user principal account is not persisted when it is created. To save the account, call the method. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml index 306de4deb9f..58f6841bf82 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml @@ -223,11 +223,11 @@ Gets or sets a value that indicates whether the replication schedule is ignored. A value that indicates whether to ignore the replication schedule. if the replication schedule is ignored; otherwise, . - is `true`, any site link availability schedules that have been configured are ignored, and all site links become always-available for replication. When set to `false`, any previously configured site link availability schedules go back into effect. If no site link availability schedules have been configured, setting this property has no effect. - + is `true`, any site link availability schedules that have been configured are ignored, and all site links become always-available for replication. When set to `false`, any previously configured site link availability schedules go back into effect. If no site link availability schedules have been configured, setting this property has no effect. + ]]> A call to the underlying directory service resulted in an error. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml index 65ef5fda443..49ca2122e1c 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchedule.xml @@ -260,7 +260,7 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; ## Remarks All of the parameters in this method are inclusive. - This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. + This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. ]]> @@ -318,7 +318,7 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; ## Remarks All of the parameters in this method are inclusive. - This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. + This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. ]]> @@ -372,7 +372,7 @@ bool isAvailable = scheduleObject.RawSchedule[2, 15, (Int32)50/15]; ## Remarks All of the parameters in this method are inclusive. - This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. + This method is cumulative and does not remove any existing schedule information. If an existing schedule and the new schedule overlap, the result will still be cumulative. To clear the schedule, use the method. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaClass.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaClass.xml index 9a3a6776d23..197010a8b0f 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaClass.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaClass.xml @@ -59,11 +59,11 @@ A that represents the LDAP display name for this object. Initializes a new instance of the object. - method must be called to commit the object that was created to the underlying directory store. - + method must be called to commit the object that was created to the underlying directory store. + ]]> @@ -343,11 +343,11 @@ Gets a collection that contains all properties, including ancestor properties, of the object. A collection of the properties of the , including ancestor properties. - collection is returned. - + collection is returned. + ]]> A call to the underlying directory service resulted in an error. @@ -650,13 +650,13 @@ Gets or sets the schemaIDGUID for the object. A object that contains the schemaIDGUID for the object. - is used in many Active Directory Domain Services configuration operations, such as managing extended rights. + is used in many Active Directory Domain Services configuration operations, such as managing extended rights. For more information, see [schemaIDGUID](https://learn.microsoft.com/openspecs/windows_protocols/ms-tail/5038cdbe-b665-429c-a36e-36a45f576b81) or [Schema-ID-GUID](/windows/desktop/adschema/a-schemaidguid). - + ]]> A call to the underlying directory service resulted in an error. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml index 3a4aa26eebe..c28285520fd 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml @@ -59,11 +59,11 @@ A that represents the LDAP display name for this object. Initializes a new instance of the class. - method must be called to commit the object that was created to the Active Directory Domain Services. - + method must be called to commit the object that was created to the Active Directory Domain Services. + ]]> @@ -570,12 +570,12 @@ Gets or sets the value for the link identifier when the schema property is linked. An value that represents the linkID value when the schema property is linked. - @@ -612,12 +612,12 @@ For more information, see the [Link-ID](/windows/desktop/adschema/a-linkid) arti Gets the ldapDisplayName of the object. A value that contains the ldapDisplayName of the object. - A call to the underlying directory service resulted in an error. @@ -773,13 +773,13 @@ For more information, see the [LDAP-Display-Name](/windows/desktop/adschema/a-ld Gets or sets the schemaIDGuid for the object. A that represents the schemaIDGuid for the object. - is used in many Active Directory Domain Services configuration operations, such as managing extended rights. + is used in many Active Directory Domain Services configuration operations, such as managing extended rights. For more information, see the [Schema-ID-GUID](/windows/desktop/adschema/a-schemaidguid) article. - + ]]> A call to the underlying directory service resulted in an error. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml index 12a34feb763..5859782df0a 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml @@ -398,11 +398,11 @@ Gets or sets the directory server that serves as the inter-site topology generator. A read/write object that represents the directory server that serves as the inter-site topology generator. - A call to the underlying directory service resulted in an error. @@ -718,11 +718,11 @@ Returns a writable collection of subnets in the site. An object that contains a writable collection of subnets in the site. - object is writable. After modification, the method should be called. - + object is writable. After modification, the method should be called. + ]]> A call to the underlying directory service resulted in an error. diff --git a/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml b/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml index 8d1d72ef0e2..aa6207c4651 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml @@ -302,7 +302,7 @@ ## Remarks > [!NOTE] -> The method refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). +> The method refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml index f00d7f9bdc1..c91acf112e5 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml @@ -96,7 +96,7 @@ The `trustPassword` parameter associates a password with the created trust. When the other side of the trust is created, the same password is provided and the two local trusts are then bound to each other. - To programmatically create both sides of a trust relationship in a single method call, use the method. + To programmatically create both sides of a trust relationship in a single method call, use the method. ]]> @@ -148,7 +148,7 @@ method is used to create only one side of a trust. + This method creates both sides of a trust relationship with a single method call. The method is used to create only one side of a trust. ]]> @@ -198,7 +198,7 @@ ## Remarks When one side of a trust relationship is deleted, the trust longer exists. - To delete both sides of a trust relationship with one method call, use the method. + To delete both sides of a trust relationship with one method call, use the method. ]]> @@ -246,7 +246,7 @@ method. + To delete only one side of a trust relationship, use the method. ]]> @@ -764,7 +764,7 @@ method is a object representing the domain to which the computer running the application is joined. This return value is independent of the domain credentials under which the application is run. This method will retrieve the computer's domain regardless of the trusted account domain credentials it is run under. To retrieve the object that represents the domain corresponding to the user credentials in effect for the security context under which the application is running, use the method instead. + The return value of the method is a object representing the domain to which the computer running the application is joined. This return value is independent of the domain credentials under which the application is run. This method will retrieve the computer's domain regardless of the trusted account domain credentials it is run under. To retrieve the object that represents the domain corresponding to the user credentials in effect for the security context under which the application is running, use the method instead. ]]> @@ -798,7 +798,7 @@ A object that represents the domain for the specified user credentials in effect for the security context under which the application is running. method is determined by the domain credentials under which the application is running. To retrieve the object representing the domain to which the computer running the application is joined, regardless of the credentials associated with that application, use the method instead. + method is determined by the domain credentials under which the application is running. To retrieve the object representing the domain to which the computer running the application is joined, regardless of the credentials associated with that application, use the method instead. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml b/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml index 4ecdd8e7a4b..80c51c60887 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml @@ -136,11 +136,11 @@ Determines if the managed resources should be released. if the managed resources are released; otherwise, . Causes the object to release all managed and/or unmanaged resources. - @@ -198,11 +198,11 @@ Promotes this domain controller to a global catalog server. A object that represents the global catalog server. - method is used to demote the domain controller from a global catalog server. - + method is used to demote the domain controller from a global catalog server. + ]]> The current object has been disposed. @@ -1012,11 +1012,11 @@ One of the members that specifies which role the domain controller should take ownership of. Causes this domain controller to take ownership of the specified role. - method should be used instead whenever possible. - + method should be used instead whenever possible. + ]]> @@ -1118,11 +1118,11 @@ A combination of one or more of the members. Causes this domain controller to synchronize the specified partition with all other domain controllers. - value, then the replication will occur with all domain controllers in the forest. - + value, then the replication will occur with all domain controllers in the forest. + ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml index 3153c88a7fd..8d08ed11ee5 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml @@ -101,7 +101,7 @@ The `trustPassword` parameter associates a password with the created trust. When the other side of the trust is created, the same password is provided and the two local trusts are then bound to each other. - To programmatically create both sides of a trust relationship in a single method call, use the method. + To programmatically create both sides of a trust relationship in a single method call, use the method. ]]> @@ -153,7 +153,7 @@ method is used to create only one side of a trust. + This method creates both sides of a trust relationship with a single method call. The method is used to create only one side of a trust. ]]> @@ -203,7 +203,7 @@ ## Remarks When one side of a trust relationship is deleted, the trust is no longer established. - To delete both sides of a trust relationship with one method call, use the method. + To delete both sides of a trust relationship with one method call, use the method. ]]> @@ -249,7 +249,7 @@ method. + To delete only one side of a trust relationship, use the method. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml b/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml index 2e64541fdc5..5d4c5394521 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml @@ -53,11 +53,11 @@ Gets the time of the last successful replication synchronization with the replication source server. The time at which the last successful replication synchronization occurred. - indicates the time when this domain controller last synchronized to changes for this partition on the source directory system agent (DSA). - + indicates the time when this domain controller last synchronized to changes for this partition on the source directory system agent (DSA). + ]]> This property is not supported on Windows 2000. diff --git a/xml/System.DirectoryServices.ActiveDirectory/SyncUpdateCallback.xml b/xml/System.DirectoryServices.ActiveDirectory/SyncUpdateCallback.xml index d3d4f269df4..f658e0247f5 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/SyncUpdateCallback.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/SyncUpdateCallback.xml @@ -36,17 +36,17 @@ if the SyncReplicaFromAllServers method invoked on a , or object should resume; if the SyncReplicaFromAllServers method should terminate. - - - operation takes a long time to complete and potentially could fail on a server. The callback function enables the application to indicate whether the SyncReplicaFromAllServers method should continue executing. For example, the application could return false to terminate - - execution if an error occurs. Another scenario in which this capability would be used is to terminate - - execution once the application detects that synchronization has completed for a certain target server or source server pair. - + + + operation takes a long time to complete and potentially could fail on a server. The callback function enables the application to indicate whether the SyncReplicaFromAllServers method should continue executing. For example, the application could return false to terminate + + execution if an error occurs. Another scenario in which this capability would be used is to terminate + + execution once the application detects that synchronization has completed for a certain target server or source server pair. + ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/TopLevelNameCollisionOptions.xml b/xml/System.DirectoryServices.ActiveDirectory/TopLevelNameCollisionOptions.xml index 6506d82b24e..9ecba7c71d8 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/TopLevelNameCollisionOptions.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/TopLevelNameCollisionOptions.xml @@ -26,13 +26,13 @@ Specifies additional information about a forest trust collision when the property value is . - - - - + + + + ]]> diff --git a/xml/System.DirectoryServices.Protocols/AddRequest.xml b/xml/System.DirectoryServices.Protocols/AddRequest.xml index f4014e6c40b..aba3469362d 100644 --- a/xml/System.DirectoryServices.Protocols/AddRequest.xml +++ b/xml/System.DirectoryServices.Protocols/AddRequest.xml @@ -28,7 +28,7 @@ or it can be used as the parameter for . + The request may be added to the or it can be used as the parameter for . ]]> diff --git a/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml b/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml index b5d8576e615..88e7d666c4b 100644 --- a/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml +++ b/xml/System.DirectoryServices.Protocols/DirectoryAttribute.xml @@ -555,7 +555,7 @@ always attempts to convert and return the value object as a string; otherwise it returns a byte array. To get a better performance, use the method if you know the return type of the attribute value. + The Get method of always attempts to convert and return the value object as a string; otherwise it returns a byte array. To get a better performance, use the method if you know the return type of the attribute value. ]]> diff --git a/xml/System.DirectoryServices.Protocols/DirectoryAttributeModification.xml b/xml/System.DirectoryServices.Protocols/DirectoryAttributeModification.xml index ce5bff9d152..cf83db811c7 100644 --- a/xml/System.DirectoryServices.Protocols/DirectoryAttributeModification.xml +++ b/xml/System.DirectoryServices.Protocols/DirectoryAttributeModification.xml @@ -67,17 +67,17 @@ The property specifies one of modifications to perform. The modification to perform. - is . - -## Exceptions - -|Exceptions|Condition| -|----------------|---------------| -|InvalidEnumArgumentException|The property value is not one of the values.| - + is . + +## Exceptions + +|Exceptions|Condition| +|----------------|---------------| +|InvalidEnumArgumentException|The property value is not one of the values.| + ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml index c1765c51049..aea1b364bf0 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml @@ -531,7 +531,7 @@ using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide synchronized versions of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml b/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml index 13071e05cdc..dac80ee3441 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml @@ -258,7 +258,7 @@ using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide synchronized versions of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml b/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml index 3a45c33bc8b..1f5b20fbbb4 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml @@ -94,7 +94,7 @@ ## Remarks The method will block while waiting for a response from the DSML server and will timeout according to the property. - If the DSML server terminates the session, a is thrown. If is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. + If the DSML server terminates the session, a is thrown. If is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. ]]> @@ -148,10 +148,10 @@ ## Remarks -The API uses and to track the lifetime of a session. +The API uses and to track the lifetime of a session. > [!CAUTION] -> Attaching an `EndSession` header to the causes the API to become inconsistent with the connection and should be avoided. +> Attaching an `EndSession` header to the causes the API to become inconsistent with the connection and should be avoided. ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml b/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml index 463f7869b14..27c5a1917ed 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml @@ -307,7 +307,7 @@ ## Remarks This method will block while waiting for a response from the DSML server and will time out according to the property. - If the DSML server has already terminated the session on its own, a will be thrown. If the is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. + If the DSML server has already terminated the session on its own, a will be thrown. If the is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. ]]> diff --git a/xml/System.DirectoryServices.Protocols/PartialResultProcessing.xml b/xml/System.DirectoryServices.Protocols/PartialResultProcessing.xml index 2ea13caf9ef..2ffd475dc45 100644 --- a/xml/System.DirectoryServices.Protocols/PartialResultProcessing.xml +++ b/xml/System.DirectoryServices.Protocols/PartialResultProcessing.xml @@ -24,15 +24,15 @@ The enumeration specifies the required type of partial results processing. - method, method, and (optionally) the delegate in the standard .NET style. - - An application retrieving partial results can call the and pass either ReturnPartialResults or ReturnPartialResultsAndNotifyCallback as the `partialMode` parameter. - - In most scenarios, use NoPartialResultSupport for better performance and scalability. The use of ReturnPartialResults or ReturnPartialResultsAndNotifyCallback is only recommended in the scenario where the retrieval of partial results is desired. For example, when performing a search with the specified, the search results are returned only when changes are made to that object. The search never completes and partial results are returned. - + method, method, and (optionally) the delegate in the standard .NET style. + + An application retrieving partial results can call the and pass either ReturnPartialResults or ReturnPartialResultsAndNotifyCallback as the `partialMode` parameter. + + In most scenarios, use NoPartialResultSupport for better performance and scalability. The use of ReturnPartialResults or ReturnPartialResultsAndNotifyCallback is only recommended in the scenario where the retrieval of partial results is desired. For example, when performing a search with the specified, the search results are returned only when changes are made to that object. The search never completes and partial results are returned. + ]]> diff --git a/xml/System.DirectoryServices/ActiveDirectorySecurity.xml b/xml/System.DirectoryServices/ActiveDirectorySecurity.xml index fb739e176e8..85d4757cc97 100644 --- a/xml/System.DirectoryServices/ActiveDirectorySecurity.xml +++ b/xml/System.DirectoryServices/ActiveDirectorySecurity.xml @@ -76,11 +76,11 @@ Gets the object that represents an access right for this object. The of the access right. - of the enumeration. - + of the enumeration. + ]]> @@ -205,11 +205,11 @@ Gets the that represents an access rule for this object. The of the access rule. - of the class. - + of the class. + ]]> @@ -393,11 +393,11 @@ Gets the that represents an audit rule for this object. The of the audit rule. - of the class. - + of the class. + ]]> @@ -741,11 +741,11 @@ The object to which this operation applies. Searches an object's DACL for all access rules that contain a security identifier (SID) that matches the SID specified in the object, and replaces all of those access rules with the access rules that are contained in the object. - is used to replace all access rules with a particular SID in an object's DACL, both Allow- and Deny- type rules are replaced. To replace only Allow rules without affecting Deny rules, or to replace Deny rules without affecting Allow rules, use instead. - + is used to replace all access rules with a particular SID in an object's DACL, both Allow- and Deny- type rules are replaced. To replace only Allow rules without affecting Deny rules, or to replace Deny rules without affecting Allow rules, use instead. + ]]> @@ -777,11 +777,11 @@ The object to which this operation applies. Searches an object's DACL for all access rules that contain a security identifier (SID) that matches the SID specified in the object, and an access control type (Allow or Deny) that matches the type specified in the object, and replaces all of those access rules with the access rules that are contained in the object. - is used to replace all access rules that match a particular SID and access control type (Allow or Deny) in an object's DACL, all rules in that DACL with an SID and type that match the SID and access control type contained in the `rule` object are replaced. Using this method, the developer can replace any Allow rules for that SID on that object without affecting existing Deny rules, or replace all Deny rules for that SID on that object without affecting existing Allow rules. To replace all rules for that object pertaining to the specified SID, regardless of type, use instead. - + is used to replace all access rules that match a particular SID and access control type (Allow or Deny) in an object's DACL, all rules in that DACL with an SID and type that match the SID and access control type contained in the `rule` object are replaced. Using this method, the developer can replace any Allow rules for that SID on that object without affecting existing Deny rules, or replace all Deny rules for that SID on that object without affecting existing Allow rules. To replace all rules for that object pertaining to the specified SID, regardless of type, use instead. + ]]> diff --git a/xml/System.DirectoryServices/DirectoryEntries.xml b/xml/System.DirectoryServices/DirectoryEntries.xml index 267d8ac4d40..a6835e61e3d 100644 --- a/xml/System.DirectoryServices/DirectoryEntries.xml +++ b/xml/System.DirectoryServices/DirectoryEntries.xml @@ -70,7 +70,7 @@ method on the new entry to make the creation permanent. When you call this method, you can then set mandatory property values on the new entry. The providers each have different requirements for properties that need to be set before a call to the method is made. If those requirements are not met, the provider might throw an exception. Check with your provider to determine which properties must be set before committing changes. + You must call the method on the new entry to make the creation permanent. When you call this method, you can then set mandatory property values on the new entry. The providers each have different requirements for properties that need to be set before a call to the method is made. If those requirements are not met, the provider might throw an exception. Check with your provider to determine which properties must be set before committing changes. ## Examples The following example creates a new object with a specified path, then creates a new entry in the container and saves it. @@ -151,7 +151,7 @@ Console.WriteLine (myDirectoryEntry.Name + " entry is created in container."); If child objects of different types have the same name, the first matching child object is returned. > [!NOTE] -> The Internet Information Services (IIS) provider does not support this method. Use the overloaded method and specify an empty string ("") for the `schemaClassName` parameter. +> The Internet Information Services (IIS) provider does not support this method. Use the overloaded method and specify an empty string ("") for the `schemaClassName` parameter. > > If no matching result is found, a with error code 0x2030 is thrown. @@ -340,7 +340,7 @@ class MyClass1 method. + If the entry to be removed is a container, the container must be empty. To delete a container and all its children, use the method. ## Examples The following example creates a new object with the specified path, then creates a new entry in the container and saves it. Finally, it retrieves the new entry and deletes it. diff --git a/xml/System.DirectoryServices/DirectoryEntry.xml b/xml/System.DirectoryServices/DirectoryEntry.xml index 978b50211ce..1f7359d1c67 100644 --- a/xml/System.DirectoryServices/DirectoryEntry.xml +++ b/xml/System.DirectoryServices/DirectoryEntry.xml @@ -49,7 +49,7 @@ The Active Directory Domain Services hierarchy contains up to several thousand nodes. Each node represents an object, such as a network printer or a user in a domain. Corporate networks constantly change as new employees are hired and objects such as network printers and computers are added. Active Directory Service Interfaces (ADSI) technology provides ways to programmatically add these objects to the directory tree. - To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. + To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. This class also contains attribute caching, which can be useful for optimizing network traffic. To use attribute caching, see the property. @@ -370,10 +370,10 @@ public class PrintChildren{ ## Remarks The child entries are only the immediate children of this node. - Use this property to find, retrieve, or create a directory entry in the hierarchy. This property is a collection that, along with the usual iteration capabilities, provides an method through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. + Use this property to find, retrieve, or create a directory entry in the hierarchy. This property is a collection that, along with the usual iteration capabilities, provides an method through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. > [!NOTE] -> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. +> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. ]]> @@ -414,7 +414,7 @@ public class PrintChildren{ ## Remarks Call this method to release unmanaged system resources, without waiting for garbage collection. - Following a call to , any operations on the might raise exceptions. + Following a call to , any operations on the might raise exceptions. ]]> @@ -448,12 +448,12 @@ public class PrintChildren{ . + By default, changes to properties are made locally to a cache, and property values to be read are cached after the first read. For more information, see . - Changes made to the cache include changes to the properties as well as calls to (if this is the newly created entry). + Changes made to the cache include changes to the properties as well as calls to (if this is the newly created entry). > [!CAUTION] -> If you call before calling , any uncommitted changes to the property cache will be lost. +> If you call before calling , any uncommitted changes to the property cache will be lost. ## Security @@ -508,9 +508,9 @@ public class PrintChildren{ is `true`, call on the new object to make the copy permanent. + If is `true`, call on the new object to make the copy permanent. - The Lightweight Directory Access Protocol (LDAP) provider does not currently support the method. + The Lightweight Directory Access Protocol (LDAP) provider does not currently support the method. ]]> @@ -561,7 +561,7 @@ public class PrintChildren{ ## Remarks The Lightweight Directory Access Protocol (LDAP) provider does not currently support this method. - If is `true`, call on the new object to make the copy permanent. + If is `true`, call on the new object to make the copy permanent. ]]> @@ -644,7 +644,7 @@ public class PrintChildren{ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`. When the `disposing` parameter is `true`, this method releases all resources that are held by any managed objects that this object references. This method invokes the `Dispose()` method of each referenced object. @@ -767,7 +767,7 @@ if (DirectoryEntry.Exists(myADSPath)) ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. +The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. ```vb Dim myADSPath As [String] = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" @@ -999,7 +999,7 @@ Console.WriteLine("The Native GUID of the ADS"+ is `true`, call the method on the new object to make the move permanent. + If is `true`, call the method on the new object to make the move permanent. ]]> @@ -1049,7 +1049,7 @@ Console.WriteLine("The Native GUID of the ADS"+ is `true`, call on the new object to make the move permanent. + If is `true`, call on the new object to make the move permanent. ]]> @@ -1100,11 +1100,11 @@ Console.WriteLine("The Native GUID of the ADS"+ , distinguishes this entry from its siblings and must be unique among its siblings in each container. + This name, along with , distinguishes this entry from its siblings and must be unique among its siblings in each container. ## Examples -The following example creates a for the node in the Active Directory Domain Services. It then displays the and properties of its child nodes. +The following example creates a for the node in the Active Directory Domain Services. It then displays the and properties of its child nodes. ```vb Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity, @@ -1190,7 +1190,7 @@ foreach(DirectoryEntry myDirectoryEntryChild in ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. +The following example demonstrates the and properties of the class. This example gets the user-specified and displays its and properties. ```vb Dim myADSPath As [String] = "LDAP://onecity/CN=Users, @@ -1403,7 +1403,7 @@ Console.WriteLine("The Native GUID of the ADS"+ ## Examples -The following example searches a given and displays the and of the result. +The following example searches a given and displays the and of the result. ```vb Dim myADSPath As String = _ @@ -1474,11 +1474,11 @@ Console.WriteLine("Parent is :"+myDirectoryEntry.Parent.Path); and properties to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. + You can set the and properties to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . +The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . ```vb Dim myADSPath As String = _ @@ -1575,14 +1575,14 @@ foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . + The property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . - Setting the retrieves a new entry from the directory store; it does not change the path of the currently bound entry. + Setting the retrieves a new entry from the directory store; it does not change the path of the currently bound entry. The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. > [!NOTE] -> The section of the that identifies the provider (precedes "://") is case-sensitive. For example, "LDAP://" or "WinNT://". +> The section of the that identifies the provider (precedes "://") is case-sensitive. For example, "LDAP://" or "WinNT://". The syntax for the property varies according to the provider. Some common scenarios are: @@ -1663,7 +1663,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); calls the ADSI interface [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) method to retrieve the value from the cache. If the underling cache has not been loaded, [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) implicitly calls [IADs::GetInfo](/windows/win32/api/iads/nf-iads-iads-getinfo). This method loads the values of the supported properties that have not been set in the cache from the underlying directory store. Subsequent calls to retrieves the property values in the cache only. To control property cache loading, call . + If the property is not initialized, calls the ADSI interface [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) method to retrieve the value from the cache. If the underling cache has not been loaded, [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) implicitly calls [IADs::GetInfo](/windows/win32/api/iads/nf-iads-iads-getinfo). This method loads the values of the supported properties that have not been set in the cache from the underlying directory store. Subsequent calls to retrieves the property values in the cache only. To control property cache loading, call . **Note** The property is not supported for use with the Active Directory Client Extension (DSClient) for Windows NT 4.0. @@ -1711,7 +1711,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); ## Remarks > [!CAUTION] -> Any uncommitted changes to the property cache will be lost. Use the method to persist changes to the directory store. +> Any uncommitted changes to the property cache will be lost. Use the method to persist changes to the directory store. ]]> @@ -1751,7 +1751,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); ## Remarks > [!CAUTION] -> Any uncommitted changes to the property cache will be lost. Use to persist changes to the directory store. +> Any uncommitted changes to the property cache will be lost. Use to persist changes to the directory store. ]]> @@ -1794,7 +1794,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); > [!NOTE] > This will also affect the path that is used to refer to this entry. - If is `true`, be sure to call the method on the new object to make the move permanent. + If is `true`, be sure to call the method on the new object to make the move permanent. ]]> @@ -1850,7 +1850,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified and gets all of its children if the is a container object. The is a container object if the of that object is "container". +The following example demonstrates the and properties of the class. This example gets the user-specified and gets all of its children if the is a container object. The is a container object if the of that object is "container". ```vb Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" @@ -1943,7 +1943,7 @@ if (string.Compare(mySchemaEntry.Name, "container") == 0) ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified object and gets all of its children if the object is a container object. The is a container object if the of that object is "container". +The following example demonstrates the and properties of the class. This example gets the user-specified object and gets all of its children if the object is a container object. The is a container object if the of that object is "container". ```vb Dim myADSPath As String = "LDAP://onecity/CN=Users,DC=onecity,DC=corp,DC=fabrikam,DC=com" @@ -2029,10 +2029,10 @@ if (string.Compare(mySchemaEntry.Name,"container") == 0) ## Remarks By default, changes to properties are made locally to a cache, and property values to be read are cached after the first read. When the property is `true`, access to the object's properties is faster. Setting this to `false` will cause the cache to be committed after each operation. - If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. + If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. > [!CAUTION] -> If you call before calling , any uncommitted changes to the property cache will be lost. +> If you call before calling , any uncommitted changes to the property cache will be lost. > [!NOTE] > The Internet Information Services (IIS) provider does not support committing the cache after each operation. @@ -2102,11 +2102,11 @@ if (string.Compare(mySchemaEntry.Name,"container") == 0) and in order to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. + You can set the and in order to specify alternate credentials with which to access the information in Active Directory Domain Services. Any other objects retrieved from this instance (for example, through ) are automatically created with the same alternate credentials. ## Examples -The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . +The following example demonstrates the and properties of the class. This example gets the user-specified and the of all its . ```vb Dim myADSPath As String = _ diff --git a/xml/System.DirectoryServices/DirectorySearcher.xml b/xml/System.DirectoryServices/DirectorySearcher.xml index 35766640de7..ac8c8192ff1 100644 --- a/xml/System.DirectoryServices/DirectorySearcher.xml +++ b/xml/System.DirectoryServices/DirectorySearcher.xml @@ -39,7 +39,7 @@ When you create an instance of , you specify the root you want to retrieve, and an optional list of properties to retrieve. The property enables you to set additional properties to do the following tasks: -- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. +- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. - Specify the length of time to search, using the property. @@ -112,10 +112,10 @@ |Property|Initial value| |--------------|-------------------| -||A null reference (`Nothing` in Visual Basic)| -||"(objectClass=*)"| -||An empty object| -||| +||A null reference (`Nothing` in Visual Basic)| +||"(objectClass=*)"| +||An empty object| +||| ]]> @@ -158,9 +158,9 @@ |Property|Initial value| |--------------|-------------------| -||"(objectClass=*)"| -||An empty object| -||| +||"(objectClass=*)"| +||An empty object| +||| ]]> @@ -203,9 +203,9 @@ |Property|Initial value| |--------------|-------------------| -||A null reference (`Nothing` in Visual Basic)| -||An empty object| -||| +||A null reference (`Nothing` in Visual Basic)| +||An empty object| +||| ]]> @@ -250,8 +250,8 @@ |Property|Initial value| |--------------|-------------------| -||An empty object.| -||| +||An empty object.| +||| ]]> @@ -303,8 +303,8 @@ |Property|Initial value| |--------------|-------------------| -||A null reference (`Nothing` in Visual Basic)| -||| +||A null reference (`Nothing` in Visual Basic)| +||| ]]> @@ -358,7 +358,7 @@ |Property|Initial value| |--------------|-------------------| -||| +||| ]]> @@ -412,7 +412,7 @@ |Property|Initial value| |--------------|-------------------| -||A null reference (`Nothing` in Visual Basic)| +||A null reference (`Nothing` in Visual Basic)| ]]> @@ -591,7 +591,7 @@ SearchResultCollection res = src.FindAll(); ## Remarks The attribute that this property is set to must be a distinguished name attribute, such as member or managedBy. The attribute can be either single or multi-valued. For more information, see the [Member](/windows/desktop/adschema/a-member) and [Managed-By](/windows/desktop/adschema/a-managedby) articles. - The search is performed against the objects that are identified by the distinguished name that is specified in the attribute of the base object. For example, if the base object is an adschema group class and the is set to "member," then the search will be performed against all objects that are members of the group. For more information, see the [Group class](/windows/desktop/adschema/c-group) article. + The search is performed against the objects that are identified by the distinguished name that is specified in the attribute of the base object. For example, if the base object is an adschema group class and the is set to "member," then the search will be performed against all objects that are members of the group. For more information, see the [Group class](/windows/desktop/adschema/c-group) article. When the property is used, the property must be set to . If the property is set to any other value, setting the property will throw an . @@ -714,7 +714,7 @@ public class Example ## Remarks The minimum resolution of this property is one second. Fractions of seconds are ignored. - If the is reached before the client times out, the server returns its results and the client stops waiting. The maximum server time limit is 120 seconds. + If the is reached before the client times out, the server returns its results and the client stops waiting. The maximum server time limit is 120 seconds. ]]> @@ -1031,7 +1031,7 @@ SearchResultCollection res = src.FindAll(); class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. + Due to implementation restrictions, the class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. ]]> @@ -1310,7 +1310,7 @@ SearchResultCollection res = src.FindAll(); is a null reference (`Nothing` in Visual Basic), the search root is set to the root of the domain that your server is currently using. + If is a null reference (`Nothing` in Visual Basic), the search root is set to the root of the domain that your server is currently using. There are several ways to search in the global catalog: @@ -1481,7 +1481,7 @@ SearchResultCollection res = src.FindAll(); When the time limit is reached, the server stops searching and returns the results that have accumulated up to that point, along with a cookie containing the information about where to resume searching. > [!NOTE] -> This property only applies to searches where is set to a value that is not the default of 0. +> This property only applies to searches where is set to a value that is not the default of 0. ]]> @@ -1529,10 +1529,10 @@ SearchResultCollection res = src.FindAll(); Unlike the property, the property indicates the total amount of time that the server will spend on a search. When the time limit is reached, the server stops searching and returns the results that have accumulated up to that point. - Set to -1 second to use the server-determined default. + Set to -1 second to use the server-determined default. > [!NOTE] -> If you set to a value that is larger than the server-determined default of 120 seconds, the server-determined default is used. After the server time limit is reached, you cannot continue a search from where it left off. +> If you set to a value that is larger than the server-determined default of 120 seconds, the server-determined default is used. After the server time limit is reached, you cannot continue a search from where it left off. ]]> @@ -1581,7 +1581,7 @@ SearchResultCollection res = src.FindAll(); The server stops searching after the size limit is reached and returns the results accumulated up to that point. > [!NOTE] -> If you set to a value that is larger than the server-determined default of 1000 entries, the server-determined default is used. +> If you set to a value that is larger than the server-determined default of 1000 entries, the server-determined default is used. ]]> diff --git a/xml/System.DirectoryServices/PropertyCollection.xml b/xml/System.DirectoryServices/PropertyCollection.xml index f7d25150664..26a78c1cc93 100644 --- a/xml/System.DirectoryServices/PropertyCollection.xml +++ b/xml/System.DirectoryServices/PropertyCollection.xml @@ -136,7 +136,7 @@ , so each will throw a . + The Internet Information Services (IIS), and WinNT providers do not currently support , so each will throw a . ]]> @@ -327,14 +327,14 @@ returns an object, which can be used to synchronize access to the . + returns an object, which can be used to synchronize access to the . Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions that result from changes made by other threads. - The following example shows how to lock the collection using the during the entire enumeration: + The following example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); @@ -392,9 +392,9 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's SyncRoot property. - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a Synchronized method on a collection, the expected usage for looks like this: + In the absence of a Synchronized method on a collection, the expected usage for looks like this: ```csharp ICollection MyCollection =... @@ -413,7 +413,7 @@ Dim myCollection as New ICollection() Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the during the entire enumeration: + The following code example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); @@ -475,12 +475,12 @@ Dim myCollection As New ICollection() property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. ## Examples - The following example shows how to implement the method. This code example is part of a larger example provided for the class. + The following example shows how to implement the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet9"::: @@ -529,7 +529,7 @@ Dim myCollection As New ICollection() method. This example is part of a larger example provided for the class. + The following example demonstrates how to implement the method. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet8"::: @@ -575,7 +575,7 @@ Dim myCollection As New ICollection() method. This example is part of a larger example provided for the class. + The following example demonstrates how to implement the method. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet5"::: @@ -721,7 +721,7 @@ Dim myCollection As New ICollection() ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]`. - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. @@ -822,7 +822,7 @@ Dim myCollection As New ICollection() method. This code example is part of a larger example provided for the class. + The following example shows how to implement the method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet7"::: @@ -875,11 +875,11 @@ Dim myCollection As New ICollection() Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until either or is called. sets to the next element. + returns the same object until either or is called. sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. To set to the first element of the collection again, you can call followed by . + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. To set to the first element of the collection again, you can call followed by . An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined. diff --git a/xml/System.DirectoryServices/PropertyValueCollection.xml b/xml/System.DirectoryServices/PropertyValueCollection.xml index d682614d8ff..d20ecf582bc 100644 --- a/xml/System.DirectoryServices/PropertyValueCollection.xml +++ b/xml/System.DirectoryServices/PropertyValueCollection.xml @@ -314,13 +314,13 @@ Gets or sets the property value that is located at a specified index of this collection. The property value at the specified index. - class. - - In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property whose type is Object and whose index type is . - + class. + + In JScript, you can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the expando attribute on a class automatically provides a default indexed property whose type is Object and whose index type is . + ]]> The property value is a null reference ( in Visual Basic). @@ -520,41 +520,41 @@ The property value to remove. Removes a specified property value from this collection. - method will successfully remove the correct item. However, identifying the correct items by name is difficult with a multi-valued DNWithString property value (as the DNWithString COM class, which is used to store the DNWithString items, has 2 string properties representing the item). The way to remove such items is to find the object in the collection (by looping thru all the items), then call the function with the object's pointer that you just found. This is illustrated in the example below. - - - -## Examples - -```csharp - -// Bind to the AD object -DirectoryEntry myUser = new DirectoryEntry("LDAP://AdServer:389/CN=MyUsername,CN=Users,DC=contoso,DC=com"); - -// Get the attribute -PropertyValueCollection testAttribute = myUser.Properties["someAttribute"]; - -// Find the item in the collection that we want to delete -DNWithString dnwsItemToRemove = null; -foreach (DNWithString dnwsItem in testAttribute) -{ - if (dnwsItem.StringValue.Equals("SomeValue")) - { - dnwsItemToRemove = dnwsItem; - break; - } -} - -// Delete it -testAttribute.Remove(dnwsItemToRemove); - -// Store the data -myUser.CommitChanges(); -``` - + method will successfully remove the correct item. However, identifying the correct items by name is difficult with a multi-valued DNWithString property value (as the DNWithString COM class, which is used to store the DNWithString items, has 2 string properties representing the item). The way to remove such items is to find the object in the collection (by looping thru all the items), then call the function with the object's pointer that you just found. This is illustrated in the example below. + + + +## Examples + +```csharp + +// Bind to the AD object +DirectoryEntry myUser = new DirectoryEntry("LDAP://AdServer:389/CN=MyUsername,CN=Users,DC=contoso,DC=com"); + +// Get the attribute +PropertyValueCollection testAttribute = myUser.Properties["someAttribute"]; + +// Find the item in the collection that we want to delete +DNWithString dnwsItemToRemove = null; +foreach (DNWithString dnwsItem in testAttribute) +{ + if (dnwsItem.StringValue.Equals("SomeValue")) + { + dnwsItemToRemove = dnwsItem; + break; + } +} + +// Delete it +testAttribute.Remove(dnwsItemToRemove); + +// Store the data +myUser.CommitChanges(); +``` + ]]> The property value is a null reference ( in Visual Basic). @@ -585,15 +585,15 @@ myUser.CommitChanges(); Gets or sets the values of the collection. - If the collection is empty, the property value is a null reference ( in Visual Basic). If the collection contains one value, the property value is that value. If the collection contains multiple values, the property value equals a copy of an array of those values. - + If the collection is empty, the property value is a null reference ( in Visual Basic). If the collection contains one value, the property value is that value. If the collection contains multiple values, the property value equals a copy of an array of those values. + If setting this property, the value or values are added to the . Setting this property to a null reference () clears the collection. - diff --git a/xml/System.DirectoryServices/SchemaNameCollection.xml b/xml/System.DirectoryServices/SchemaNameCollection.xml index e132f25d614..4e7f4d5c5f7 100644 --- a/xml/System.DirectoryServices/SchemaNameCollection.xml +++ b/xml/System.DirectoryServices/SchemaNameCollection.xml @@ -561,14 +561,14 @@ returns an object, which can be used to synchronize access to the . + returns an object, which can be used to synchronize access to the . Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following example shows how to lock the collection using the during the entire enumeration: + The following example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); @@ -632,9 +632,9 @@ Dim myCollection As New ICollection() ## Remarks For collections with an underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: + In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: ```csharp ICollection MyCollection =... @@ -653,7 +653,7 @@ Dim myCollection as New ICollection() Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following example shows how to lock the collection using the during the entire enumeration: + The following example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); diff --git a/xml/System.DirectoryServices/SearchResult.xml b/xml/System.DirectoryServices/SearchResult.xml index 432de2e4c59..5abdad49208 100644 --- a/xml/System.DirectoryServices/SearchResult.xml +++ b/xml/System.DirectoryServices/SearchResult.xml @@ -32,11 +32,11 @@ ## Remarks -Instances of the class are very similar to instances of class. The crucial difference is that the class retrieves its information from the Active Directory Domain Services hierarchy each time a new object is accessed, whereas the data for is already available in the , where it gets returned from a query that is performed with the class. Only those properties that are specified through the collection in your query will be available from . +Instances of the class are very similar to instances of class. The crucial difference is that the class retrieves its information from the Active Directory Domain Services hierarchy each time a new object is accessed, whereas the data for is already available in the , where it gets returned from a query that is performed with the class. Only those properties that are specified through the collection in your query will be available from . ## Examples -The following example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry identified in the search results. +The following example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry identified in the search results. ```vb Imports System @@ -194,14 +194,14 @@ public class MySample ## Remarks -Use when you want to look at the live entry instead of the entry that was returned through , or when you want to invoke a method on the object that was returned. +Use when you want to look at the live entry instead of the entry that was returned through , or when you want to invoke a method on the object that was returned. > [!NOTE] -> Calling on each returned through can be slow. +> Calling on each returned through can be slow. ## Examples -The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. +The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. ```vb ' Get the 'DirectoryEntry' that corresponds to 'mySearchResult'. @@ -259,7 +259,7 @@ The property uniquely identifi ## Examples -The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. +The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. This example shows how to parse the property from the search result. @@ -308,11 +308,11 @@ Console.WriteLine("The path for the 'mySearchResult' search " ## Remarks -This collection only contains properties that were explicitly requested through . +This collection only contains properties that were explicitly requested through . ## Examples -The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. +The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. In this example, the search result is put into a . Then, each property is displayed to the console window. diff --git a/xml/System.DirectoryServices/SearchResultCollection.xml b/xml/System.DirectoryServices/SearchResultCollection.xml index e471c3d4b5d..b7382272ebc 100644 --- a/xml/System.DirectoryServices/SearchResultCollection.xml +++ b/xml/System.DirectoryServices/SearchResultCollection.xml @@ -41,7 +41,7 @@ class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. + Due to implementation restrictions, the class cannot release all of its unmanaged resources when it is garbage collected. To prevent a memory leak, you must call the method when the object is no longer needed. ]]> @@ -181,9 +181,9 @@ method, it allows the resources that are used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + The method, it allows the resources that are used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - The garbage collector does not release memory for a object. Therefore, an application must call the method explicitly to prevent a memory leak. + The garbage collector does not release memory for a object. Therefore, an application must call the method explicitly to prevent a memory leak. ]]> @@ -221,15 +221,15 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with the `disposing` parameter set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with the `disposing` parameter set to `false`. When the `disposing` parameter is `true`, this method releases all resources that are held by any managed objects that this references. - The garbage collector does not release memory for a object. Therefore, you must call the method explicitly to prevent a memory leak. + The garbage collector does not release memory for a object. Therefore, you must call the method explicitly to prevent a memory leak. - This method invokes the method of each object in the collection. + This method invokes the method of each object in the collection. - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). ]]> @@ -508,14 +508,14 @@ returns an object, which can be used to synchronize access to the . + returns an object, which can be used to synchronize access to the . Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the during the entire enumeration: + The following code example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); @@ -573,9 +573,9 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: + In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: ```csharp ICollection MyCollection =... @@ -594,7 +594,7 @@ Dim myCollection as New ICollection() Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the during the entire enumeration: + The following code example shows how to lock the collection using the during the entire enumeration: ```csharp ICollection myCollection = new ICollection(); diff --git a/xml/System.Drawing.Design/IPropertyValueUIService.xml b/xml/System.Drawing.Design/IPropertyValueUIService.xml index 1608632f41b..b8dd876ca3b 100644 --- a/xml/System.Drawing.Design/IPropertyValueUIService.xml +++ b/xml/System.Drawing.Design/IPropertyValueUIService.xml @@ -27,22 +27,22 @@ Provides an interface to manage the images, ToolTips, and event handlers for the properties of a component displayed in a property browser. - interface to provide objects for any properties of the component. A associated with a property can provide an image, a ToolTip and an event handler for the event that is raised when the image associated with the property is clicked. - - The interface provides methods to add, remove, and retrieve delegates to or from an internal list. When the properties of a component are displayed in a property browser, each in the list is given an opportunity to provide a for each property of the component. - - When a property browser is set to display the properties of an object, it calls the method of this interface for each property of the component, passing a that represents the property. The method calls each that has been added to the service. Each can add a to the parameter passed in the `valueUIItemList` parameter to supply UI items for the property represented by the passed in the `propDesc` parameter. - - A can contain an image to display next to the property name, a ToolTip string, and an event handler to invoke when an image associated with the property is double-clicked. - -## Examples - The following code example creates a component that obtains an instance of the interface and adds a to the service. The handler provides a object for any properties of the component named `HorizontalMargin` or `VerticalMargin`. The for these properties provides an image, a ToolTip, and an event handler that displays a message box when the image for the property is clicked. The image and the ToolTip are displayed in a when the grid is showing these properties of the component. - + interface to provide objects for any properties of the component. A associated with a property can provide an image, a ToolTip and an event handler for the event that is raised when the image associated with the property is clicked. + + The interface provides methods to add, remove, and retrieve delegates to or from an internal list. When the properties of a component are displayed in a property browser, each in the list is given an opportunity to provide a for each property of the component. + + When a property browser is set to display the properties of an object, it calls the method of this interface for each property of the component, passing a that represents the property. The method calls each that has been added to the service. Each can add a to the parameter passed in the `valueUIItemList` parameter to supply UI items for the property represented by the passed in the `propDesc` parameter. + + A can contain an image to display next to the property name, a ToolTip string, and an event handler to invoke when an image associated with the property is double-clicked. + +## Examples + The following code example creates a component that obtains an instance of the interface and adds a to the service. The handler provides a object for any properties of the component named `HorizontalMargin` or `VerticalMargin`. The for these properties provides an image, a ToolTip, and an event handler that displays a message box when the image for the property is clicked. The image and the ToolTip are displayed in a when the grid is showing these properties of the component. + :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/IPropertyValueUIService/Overview/propertyuicomponent.cs" id="Snippet1"::: - + ]]> @@ -84,11 +84,11 @@ The property value UI handler to add. Adds the specified to this service. - is called, each handler added to this service is called and given the opportunity to add an icon for the property. - + is called, each handler added to this service is called and given the opportunity to add an icon for the property. + ]]> @@ -207,11 +207,11 @@ Occurs when the list of objects is modified. - objects can call when they change their list of items. - + objects can call when they change their list of items. + ]]> diff --git a/xml/System.Drawing.Design/IToolboxService.xml b/xml/System.Drawing.Design/IToolboxService.xml index 90491287cac..f452c89db4b 100644 --- a/xml/System.Drawing.Design/IToolboxService.xml +++ b/xml/System.Drawing.Design/IToolboxService.xml @@ -48,41 +48,41 @@ - The property indicates the currently selected toolbox category. -- The method retrieves the items on the toolbox, optionally filtered by a specified toolbox category. +- The method retrieves the items on the toolbox, optionally filtered by a specified toolbox category. -- The method retrieves the currently selected . +- The method retrieves the currently selected . -- The method selects the specified as the current toolbox item. +- The method selects the specified as the current toolbox item. -- The method indicates whether the specified serialized object, if it is a , is supported by the specified designer host, or whether it matches the specified attributes. +- The method indicates whether the specified serialized object, if it is a , is supported by the specified designer host, or whether it matches the specified attributes. -- The method indicates whether the specified serialized object is a . +- The method indicates whether the specified serialized object is a . You can add and remove toolbox items with the following methods: -- The method adds a to the toolbox, creating the optionally specified category if it does not exist. +- The method adds a to the toolbox, creating the optionally specified category if it does not exist. -- The method adds a that is only enabled for the current project to the toolbox. +- The method adds a that is only enabled for the current project to the toolbox. -- The method removes the specified . +- The method removes the specified . -- The method adds a delegate capable of converting some type of data stored on the toolbox to a . +- The method adds a delegate capable of converting some type of data stored on the toolbox to a . -- The method removes any delegates for the specified data type. +- The method removes any delegates for the specified data type. You can refresh the toolbox, mark a toolbox item as used, or set the mouse cursor to a cursor that represents the current toolbox item using the following methods: -- The method refreshes the toolbox display to reflect the current state of the toolbox items. +- The method refreshes the toolbox display to reflect the current state of the toolbox items. -- The method signals the toolbox that the selected toolbox item has been used. +- The method signals the toolbox that the selected toolbox item has been used. -- The method sets the mouse cursor to a cursor that represents the current toolbox item. +- The method sets the mouse cursor to a cursor that represents the current toolbox item. You can use the toolbox to serialize or deserialize a toolbox item using the following methods: -- The method attempts to return a from the specified serialized toolbox item object. +- The method attempts to return a from the specified serialized toolbox item object. -- The method returns a serialized object representing the specified . +- The method returns a serialized object representing the specified . @@ -152,7 +152,7 @@ . If a creator handles more than one format, call more than once. Unexpected behavior may result if you add more than one creator for the same format. + A toolbox item creator can convert data of a particular data format that has been pasted or dropped on the toolbox into a . If a creator handles more than one format, call more than once. Unexpected behavior may result if you add more than one creator for the same format. ]]> @@ -201,7 +201,7 @@ . If a creator handles more than one format, call more than once. Unexpected behavior may result if you add more than one creator for the same format. + A toolbox item creator can convert data of a particular data format that has been pasted or dropped on the toolbox into a . If a creator handles more than one format, call more than once. Unexpected behavior may result if you add more than one creator for the same format. If the `host` parameter is set to `null`, the creator will be available to all designers. If a designer host is supplied, the creator will only be available to designers using the specified host. @@ -984,7 +984,7 @@ method is used to indicate to the toolbox service that the user wants to update the cache of toolbox items. If the toolbox service maintains a live list of toolbox item containers, then this method will do nothing. If it maintains a snapshot of toolbox item containers, calling this method should ensure that the snapshot is up to date. + The method is used to indicate to the toolbox service that the user wants to update the cache of toolbox items. If the toolbox service maintains a live list of toolbox item containers, then this method will do nothing. If it maintains a snapshot of toolbox item containers, calling this method should ensure that the snapshot is up to date. ]]> diff --git a/xml/System.Drawing.Design/IToolboxUser.xml b/xml/System.Drawing.Design/IToolboxUser.xml index 50fa5c25636..95001902170 100644 --- a/xml/System.Drawing.Design/IToolboxUser.xml +++ b/xml/System.Drawing.Design/IToolboxUser.xml @@ -27,20 +27,20 @@ Defines an interface for setting the currently selected toolbox item and indicating whether a designer supports a particular toolbox item. - method indicates whether the specified can be used when the current designer is active. The method selects the specified . - - - -## Examples - The following code example demonstrates an implementation of the interface that can restrict support for specific types of objects. - + method indicates whether the specified can be used when the current designer is active. The method selects the specified . + + + +## Examples + The following code example demonstrates an implementation of the interface that can restrict support for specific types of objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IToolboxUserExample/CPP/samplecontrol.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: + ]]> @@ -83,20 +83,20 @@ if the tool is supported by the toolbox and can be enabled; if the document designer does not know how to use the tool. - interface, then the tool will be enabled in the toolbox when this designer has focus. Otherwise, it will be disabled. Once a tool is marked as enabled or disabled, it may not be tested for support with the same designer again. - - - -## Examples - The following code example demonstrates an implementation of the method. - + interface, then the tool will be enabled in the toolbox when this designer has focus. Otherwise, it will be disabled. Once a tool is marked as enabled or disabled, it may not be tested for support with the same designer again. + + + +## Examples + The following code example demonstrates an implementation of the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IToolboxUserExample/CPP/samplecontrol.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet2"::: + ]]> @@ -137,11 +137,11 @@ The to select. Selects the specified tool. - is called when the user double-clicks on a toolbox item. The document designer should create a component for the specified tool. The Visual Studio integrated development environment will only call on tools that are enabled in the toolbox. - + is called when the user double-clicks on a toolbox item. The document designer should create a component for the specified tool. The Visual Studio integrated development environment will only call on tools that are enabled in the toolbox. + ]]> diff --git a/xml/System.Drawing.Design/IconEditor.xml b/xml/System.Drawing.Design/IconEditor.xml index 73b001dc3da..3abd7996e18 100644 --- a/xml/System.Drawing.Design/IconEditor.xml +++ b/xml/System.Drawing.Design/IconEditor.xml @@ -137,11 +137,11 @@ Creates a string representing the valid file extensions for icons. A string containing the icon file extensions, or if is or empty. - method is used in the for choosing icon files. - + method is used in the for choosing icon files. + ]]> @@ -192,11 +192,11 @@ Creates a filter string for the file dialog box. The filter string, created from the string returned by . - method is used in the for filtering icon files. - + method is used in the for filtering icon files. + ]]> @@ -252,11 +252,11 @@ Edits the given object value using the editor style provided by the method. The new value of the object. If the value of the object has not changed, this should return the same object it was passed. - @@ -301,11 +301,11 @@ Retrieves the editing style of the method. One of the values indicating the provided editing style. - method is not supported, the method will return . - + method is not supported, the method will return . + ]]> @@ -509,11 +509,11 @@ What to paint and where to paint it. Paints a representative value of the given object to the provided canvas. - diff --git a/xml/System.Drawing.Design/ImageEditor.xml b/xml/System.Drawing.Design/ImageEditor.xml index 266b7c8f708..6e33533f4c1 100644 --- a/xml/System.Drawing.Design/ImageEditor.xml +++ b/xml/System.Drawing.Design/ImageEditor.xml @@ -59,20 +59,20 @@ Provides a user interface for selecting an image for a property in a property grid. - is a that provides a user interface for the user to select an image for a property. When the user starts the editor, it displays an **Open File** dialog box that enables the user to navigate to a directory and select a file. The file list is initially filtered by the default file name extensions for the editor. - - - -## Examples - The following code example uses an to associate the with a property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/EditorAttributesExample/CPP/class1.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/CollectionEditor/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/CollectionEditor/Overview/class1.vb" id="Snippet3"::: - + is a that provides a user interface for the user to select an image for a property. When the user starts the editor, it displays an **Open File** dialog box that enables the user to navigate to a directory and select a file. The file list is initially filtered by the default file name extensions for the editor. + + + +## Examples + The following code example uses an to associate the with a property. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/EditorAttributesExample/CPP/class1.cpp" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/CollectionEditor/Overview/class1.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/CollectionEditor/Overview/class1.vb" id="Snippet3"::: + ]]> @@ -166,11 +166,11 @@ Creates a string of file name extensions using the specified array of file extensions and the specified separator. A string containing the specified file name extensions, each separated by the specified separator. - @@ -267,11 +267,11 @@ Edits the specified object value using the edit style provided by the method. An representing the new value. If the value of the object has not changed, returns the object that was passed to it. - @@ -316,11 +316,11 @@ Gets the editing style of the method. One of the values indicating the supported editing style. - method is not supported, this method will return . - + method is not supported, this method will return . + ]]> @@ -400,11 +400,11 @@ Gets the description for the default file-list filter provided by this editor. The description for the default file-list filter. - @@ -572,11 +572,11 @@ A indicating what to paint and where to paint it. Paints a value indicated by the specified . - contained within the specified . - + contained within the specified . + ]]> diff --git a/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml b/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml index 41007bd864f..c70cc3c45ba 100644 --- a/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml +++ b/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml @@ -42,7 +42,7 @@ event of the that the icon is associated with. The event typically launches a user interface (UI) to edit the property's value. Add a to the property of a to assign an event handler to perform the appropriate behavior when the icon displayed next to the property name is double-clicked. + Double-clicking an icon in the Properties window will raise the event of the that the icon is associated with. The event typically launches a user interface (UI) to edit the property's value. Add a to the property of a to assign an event handler to perform the appropriate behavior when the icon displayed next to the property name is double-clicked. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). diff --git a/xml/System.Drawing.Design/ToolboxItem.xml b/xml/System.Drawing.Design/ToolboxItem.xml index 8b3f57d3cce..1ea67cf5a51 100644 --- a/xml/System.Drawing.Design/ToolboxItem.xml +++ b/xml/System.Drawing.Design/ToolboxItem.xml @@ -49,13 +49,13 @@ ## Remarks is a base class for toolbox items that can be displayed in the toolbox of a design-time environment. A toolbox item typically represents a component to create when invoked on a design mode document. The class provides the methods and properties needed to provide the toolbox with the display properties for the toolbox item, to create a component or components when used, and to serialize and deserialize itself for persistence within the toolbox database. - An instance of the class can be configured with a name, bitmap, and type to create, without creating a class that derives from . The class also provides a base class for custom toolbox item implementations. A custom can create multiple components. To implement a custom toolbox item, you must derive from and override the , , and methods. + An instance of the class can be configured with a name, bitmap, and type to create, without creating a class that derives from . The class also provides a base class for custom toolbox item implementations. A custom can create multiple components. To implement a custom toolbox item, you must derive from and override the , , and methods. The following properties and methods must be configured for a to function correctly: - The property specifies the label for the toolbox item when displayed in a toolbox. -- The property specifies the fully qualified name of the type of the component that the item creates. If a derived class creates multiple components, the property may or may not be used, contingent on whether a method override depends on the value of this property. +- The property specifies the fully qualified name of the type of the component that the item creates. If a derived class creates multiple components, the property may or may not be used, contingent on whether a method override depends on the value of this property. - The property specifies the assembly that contains the type of a component that the item creates. @@ -63,19 +63,19 @@ - The property optionally contains any objects that determine whether the toolbox item can be used on a particular component. -- The method returns the component instance or instances to insert where this tool is used. +- The method returns the component instance or instances to insert where this tool is used. -- The method saves the toolbox item to a specified . +- The method saves the toolbox item to a specified . -- The method configures the toolbox item from the state information contained in the specified . +- The method configures the toolbox item from the state information contained in the specified . -- The method configures the toolbox item to create the specified type of component, if the method has not been overridden to behave differently. +- The method configures the toolbox item to create the specified type of component, if the method has not been overridden to behave differently. - The property indicates whether the properties of the toolbox item can be changed. A toolbox item is typically locked after it is added to a toolbox. -- The method locks a toolbox item. +- The method locks a toolbox item. -- The method throws an exception if the property is `true`. +- The method throws an exception if the property is `true`. @@ -112,7 +112,7 @@ constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet3"::: @@ -158,7 +158,7 @@ constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet3"::: @@ -203,7 +203,7 @@ constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the constructor in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet3"::: @@ -330,7 +330,7 @@ method throws an if the property of the is set to `true`. + The method throws an if the property of the is set to `true`. ]]> @@ -551,7 +551,7 @@ method calls the method to retrieve an array of type containing the components to create. + The method calls the method to retrieve an array of type containing the components to create. ]]> @@ -597,7 +597,7 @@ method calls the method to retrieve an array of type containing the components to create. + The method calls the method to retrieve an array of type containing the components to create. ]]> @@ -645,7 +645,7 @@ method calls the method to retrieve an array of type containing the components to create. + The method calls the method to retrieve an array of type containing the components to create. ]]> @@ -700,7 +700,7 @@ method adds the new components to the designer. + If `host` is not `null`, the method adds the new components to the designer. ]]> @@ -751,12 +751,12 @@ method adds the new components to the designer. + If `host` is not `null`, the method adds the new components to the designer. ## Examples - The following code example demonstrates the use of the method in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the method in a class derived from for a custom toolbox item implementation. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet5"::: @@ -1085,7 +1085,7 @@ method enables a property to always clone values, or to provide a default value when none exists. + The method enables a property to always clone values, or to provide a default value when none exists. ]]> @@ -1280,7 +1280,7 @@ method configures the toolbox item to create the specified type, if the method has not been overridden to behave differently. + The method configures the toolbox item to create the specified type, if the method has not been overridden to behave differently. This method performs the following operations: @@ -1473,11 +1473,11 @@ method raises the event. This method is called after a toolbox item is invoked to create components and the method has returned. + The method raises the event. This method is called after a toolbox item is invoked to create components and the method has returned. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. ]]> @@ -1526,11 +1526,11 @@ method raises the event. This method is called after a toolbox item is invoked to create components, just before the method is called. + The method raises the event. This method is called after a toolbox item is invoked to create components, just before the method is called. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. ]]> @@ -1622,7 +1622,7 @@ ## Remarks The property dictionary becomes read-only after the toolbox item has been locked. - Values in the properties dictionary are validated through the method, and default values are obtained from the method. + Values in the properties dictionary are validated through the method, and default values are obtained from the method. ]]> @@ -1862,7 +1862,7 @@ method is called as a helper method to the method. + The method is called as a helper method to the method. ]]> @@ -1920,7 +1920,7 @@ method is called whenever a value is set in the property dictionary. With this method, you can change the value of an object before committing it, or reject it by throwing an exception. + The method is called whenever a value is set in the property dictionary. With this method, you can change the value of an object before committing it, or reject it by throwing an exception. ]]> diff --git a/xml/System.Drawing.Design/ToolboxItemCollection.xml b/xml/System.Drawing.Design/ToolboxItemCollection.xml index ef4e0d0f880..35a2edc869f 100644 --- a/xml/System.Drawing.Design/ToolboxItemCollection.xml +++ b/xml/System.Drawing.Design/ToolboxItemCollection.xml @@ -78,15 +78,15 @@ An array of type containing the toolbox items to fill the collection with. Initializes a new instance of the class using the specified array of toolbox items. - instance initialized using an array of objects. - + instance initialized using an array of objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxItemCollectionExample/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet1"::: + ]]> @@ -123,15 +123,15 @@ A to fill the new collection with. Initializes a new instance of the class using the specified collection. - instance initialized using another . - + instance initialized using another . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxItemCollectionExample/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet2"::: + ]]> @@ -173,15 +173,15 @@ if the collection contains the specified object; otherwise, . - method of a . - + method of a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxItemCollectionExample/CPP/class1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet5"::: + ]]> @@ -223,15 +223,15 @@ The index to begin copying to. Copies the collection to the specified array beginning with the specified destination index. - method of a . - + method of a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxItemCollectionExample/CPP/class1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet6"::: + ]]> @@ -310,15 +310,15 @@ Gets the at the specified index. A at each valid index in the collection. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxItemCollectionExample/CPP/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/ToolboxItemCollection/.ctor/class1.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Drawing.Design/ToolboxItemContainer.xml b/xml/System.Drawing.Design/ToolboxItemContainer.xml index 6ecc309aaac..b904a1ce0dc 100644 --- a/xml/System.Drawing.Design/ToolboxItemContainer.xml +++ b/xml/System.Drawing.Design/ToolboxItemContainer.xml @@ -299,7 +299,7 @@ ## Remarks The `creators` parameter is a collection of objects that represent any custom creators that should be included when the is obtained. This parameter can be `null` if no creators are needed. - The method returns a that represents the data stored in the . never returns `null`, nor does it ever raise an exception, except in extreme cases (for example, out of memory). If a cannot be fabricated, the appropriate exception is embedded within a special . The exception is thrown when the method on this special is called. This puts the exception at the point of user action. + The method returns a that represents the data stored in the . never returns `null`, nor does it ever raise an exception, except in extreme cases (for example, out of memory). If a cannot be fabricated, the appropriate exception is embedded within a special . The exception is thrown when the method on this special is called. This puts the exception at the point of user action. ]]> @@ -463,7 +463,7 @@ method when the toolbox item is modified or configured. You should also call it if a new , which the changes the filter, is added. + You should call the method when the toolbox item is modified or configured. You should also call it if a new , which the changes the filter, is added. ]]> diff --git a/xml/System.Drawing.Design/ToolboxItemCreator.xml b/xml/System.Drawing.Design/ToolboxItemCreator.xml index e671bd0838e..8689965b930 100644 --- a/xml/System.Drawing.Design/ToolboxItemCreator.xml +++ b/xml/System.Drawing.Design/ToolboxItemCreator.xml @@ -17,11 +17,11 @@ Encapsulates a . This class cannot be inherited. - class encapsulates toolbox item creator callback functions. These callback functions are used by designers to provide ways to create toolbox items for custom data objects. - + class encapsulates toolbox item creator callback functions. These callback functions are used by designers to provide ways to create toolbox items for custom data objects. + ]]> @@ -54,13 +54,13 @@ Creates a new from a . A new instance of the class. - class. It might contain data that can be read by one of the classes that have been supplied by the user. It might also be data with a Clipboard format that has a assigned to it. In this case, the is created on demand. - - The method might raise an exception if the data object does not contain data for the supported format. - + class. It might contain data that can be read by one of the classes that have been supplied by the user. It might also be data with a Clipboard format that has a assigned to it. In this case, the is created on demand. + + The method might raise an exception if the data object does not contain data for the supported format. + ]]> @@ -94,11 +94,11 @@ Gets the Clipboard format that represents the data needed to deserialize a . A string representing the Clipboard format. - instances. If a supports any of the dragged Clipboard formats, a is created from the . - + instances. If a supports any of the dragged Clipboard formats, a is created from the . + ]]> diff --git a/xml/System.Drawing.Design/ToolboxItemCreatorCallback.xml b/xml/System.Drawing.Design/ToolboxItemCreatorCallback.xml index cb12d631209..227d0524a28 100644 --- a/xml/System.Drawing.Design/ToolboxItemCreatorCallback.xml +++ b/xml/System.Drawing.Design/ToolboxItemCreatorCallback.xml @@ -38,22 +38,22 @@ Provides a callback mechanism that can create a . The deserialized object specified by . - to store text pasted to the toolbox from the clipboard. You can use the method of the to add a event handler for a particular data type to the toolbox. The `serializedObject` parameter contains the data object. - - When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following example provides a component that uses the to add a "Text" data format handler, or , to the toolbox. The data creator callback delegate passes any text data pasted to the toolbox and dragged onto a form to a custom that creates a containing the text. - + to store text pasted to the toolbox from the clipboard. You can use the method of the to add a event handler for a particular data type to the toolbox. The `serializedObject` parameter contains the data object. + + When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following example provides a component that uses the to add a "Text" data format handler, or , to the toolbox. The data creator callback delegate passes any text data pasted to the toolbox and dragged onto a form to a custom that creates a containing the text. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ToolboxCreatorCallbackSample/CPP/textdatatextboxcomponent.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/IToolboxService/Overview/textdatatextboxcomponent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/IToolboxService/Overview/textdatatextboxcomponent.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Design/IToolboxService/Overview/textdatatextboxcomponent.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Drawing.Design/ToolboxService.xml b/xml/System.Drawing.Design/ToolboxService.xml index 59c66cad315..5b1729f5de3 100644 --- a/xml/System.Drawing.Design/ToolboxService.xml +++ b/xml/System.Drawing.Design/ToolboxService.xml @@ -133,7 +133,7 @@ method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. + The method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. The data object passed in should contain data obtained from a prior call to the property on a toolbox item container. @@ -177,7 +177,7 @@ method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. + The method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. If the provided link parameter is assigned, it indicates that this is a linked toolbox item. @@ -228,7 +228,7 @@ ## Remarks The items in the list must be objects. If the toolbox implementation is organized in categories, this retrieves a combined list of all categories. The list must be read/write, as new items may be added to it. - When the toolbox service adds a new item, it first calls the method and then adds the new item to the returned from the method. + When the toolbox service adds a new item, it first calls the method and then adds the new item to the returned from the method. If a category name is provided, only the items in that category should be returned. If no category is specified, all items should be returned. @@ -286,7 +286,7 @@ method should throw a meaningful exception. + If the category specified by the `categoryName` parameter does not exist, the method should throw a meaningful exception. ]]> @@ -408,7 +408,7 @@ method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: + The method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: - Be public. @@ -420,7 +420,7 @@ - Not contain generic parameters. - Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. + Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. Assemblies loaded in this manner are loaded into a separate so they can later be unloaded. This only momentarily locks the assembly file. @@ -468,7 +468,7 @@ method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: + The method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: - Be public. @@ -480,7 +480,7 @@ - Not contain generic parameters. - Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. + Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. ]]> @@ -520,7 +520,7 @@ method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: + The method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: - Be public. @@ -532,7 +532,7 @@ - Not contain generic parameters. - Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. + Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. ]]> @@ -572,7 +572,7 @@ method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: + The method scans the assembly for all types that support toolbox items, and return items for those types. To support a toolbox item, a type must have the following characteristics: - Be public. @@ -584,7 +584,7 @@ - Not contain generic parameters. - Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. + Assemblies are locked for the duration of a process, so enumerating various files through can cause many assemblies to be loaded. The methods that take an assembly name create a separate to search assemblies. When you are finished enumerating objects for a set of assemblies, you can call the method, which unloads the and frees the file references on the loaded assemblies. ]]> @@ -624,7 +624,7 @@ ## Remarks The data object may directly represent an item container, or there may be a custom toolbox creator that is registered to handle the format contained within the data object. - If the `host` parameter is a valid designer host, the method searches toolbox item creators that are associated with the designer host. If `host` is supplied, toolbox item creators that are associated with the host are also compared. + If the `host` parameter is a valid designer host, the method searches toolbox item creators that are associated with the designer host. If `host` is supplied, toolbox item creators that are associated with the host are also compared. ]]> @@ -687,7 +687,7 @@ method is called by the toolbox service when a user has requested that the collection of items should be refreshed. If the collection is always current, there is no need to provide any implementation here. If the collection returned from represents a snapshot of the toolbox items, however, this method provides an opportunity to update them. + The method is called by the toolbox service when a user has requested that the collection of items should be refreshed. If the collection is always current, there is no need to provide any implementation here. If the collection returned from represents a snapshot of the toolbox items, however, this method provides an opportunity to update them. ]]> @@ -773,7 +773,7 @@ method is called by the toolbox service when a user reports that the selected toolbox item has been used. After invoking a toolbox item, it is a common user interface (UI) behavior to cancel the selection of that toolbox item. The default implementation of this method cancels the selection of the toolbox item by setting the selected item container to `null`. + The method is called by the toolbox service when a user reports that the selected toolbox item has been used. After invoking a toolbox item, it is a common user interface (UI) behavior to cancel the selection of that toolbox item. The default implementation of this method cancels the selection of the toolbox item by setting the selected item container to `null`. ]]> @@ -804,7 +804,7 @@ method can be called to set the cursor. It returns `true` if the cursor is set, or `false` if it is not. The default implementation sets the cursor to a crosshair and returns `true` if there is an item selected. It returns `false` and leaves the cursor unchanged if no item is selected. + The toolbox service provides support for setting the user interface (UI) cursor to an image that represents the currently selected toolbox item. The method can be called to set the cursor. It returns `true` if the cursor is set, or `false` if it is not. The default implementation sets the cursor to a crosshair and returns `true` if there is an item selected. It returns `false` and leaves the cursor unchanged if no item is selected. ]]> diff --git a/xml/System.Drawing.Design/UITypeEditor.xml b/xml/System.Drawing.Design/UITypeEditor.xml index 020caabe0d5..90ef7503284 100644 --- a/xml/System.Drawing.Design/UITypeEditor.xml +++ b/xml/System.Drawing.Design/UITypeEditor.xml @@ -46,15 +46,15 @@ - Define a class that derives from . -- Override the method to handle the user interface, user input processing, and value assignment. +- Override the method to handle the user interface, user input processing, and value assignment. -- Override the method to inform the Properties window of the type of editor style that the editor will use. +- Override the method to inform the Properties window of the type of editor style that the editor will use. You can add additional support for painting a value's representation in the Properties window by performing the following steps: -- Override the method to indicate that the editor supports displaying the value's representation. +- Override the method to indicate that the editor supports displaying the value's representation. -- Override the method to implement the display of the value's representation. +- Override the method to implement the display of the value's representation. - Override the constructor method if the editor should have initialization behavior. @@ -298,7 +298,7 @@ does not override and implement this method, will return by default. + If a does not override and implement this method, will return by default. ]]> @@ -523,7 +523,7 @@ ## Remarks Editors should paint within the boundaries of the specified rectangle. This rectangle indicates the area of the Properties window to draw a representation of the value within. - Starting with the .NET Framework 4.6, the rectangle specified by will be resized based on the system DPI setting when the app.config file contains the following entry: + Starting with the .NET Framework 4.6, the rectangle specified by will be resized based on the system DPI setting when the app.config file contains the following entry: ``` @@ -589,7 +589,7 @@ ## Remarks Editors should paint within the boundaries of the specified rectangle. This rectangle indicates the area of the Properties window to draw a representation of the value within. - Starting with the .NET Framework 4.6, the rectangle specified by will be resized based on the system DPI setting when the app.config file contains the following entry: + Starting with the .NET Framework 4.6, the rectangle specified by will be resized based on the system DPI setting when the app.config file contains the following entry: ``` diff --git a/xml/System.Drawing.Drawing2D/AdjustableArrowCap.xml b/xml/System.Drawing.Drawing2D/AdjustableArrowCap.xml index ce975156c99..b33151cc38b 100644 --- a/xml/System.Drawing.Drawing2D/AdjustableArrowCap.xml +++ b/xml/System.Drawing.Drawing2D/AdjustableArrowCap.xml @@ -98,13 +98,13 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an object named `myArrow`. -- Creates a object named `capPen`, and sets its and properties equal to `myArrow`. +- Creates a object named `capPen`, and sets its and properties equal to `myArrow`. -- Uses the method to draw to screen a line capped by two arrows. +- Uses the method to draw to screen a line capped by two arrows. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet1"::: @@ -155,13 +155,13 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an object named `myArrow`. -- Creates a object named `capPen`, and sets its and properties equal to `myArrow`. +- Creates a object named `capPen`, and sets its and properties equal to `myArrow`. -- Uses the method to draw to screen a line capped by two arrows. +- Uses the method to draw to screen a line capped by two arrows. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet2"::: diff --git a/xml/System.Drawing.Drawing2D/Blend.xml b/xml/System.Drawing.Drawing2D/Blend.xml index de3fd1fa5b4..e8f574382b4 100644 --- a/xml/System.Drawing.Drawing2D/Blend.xml +++ b/xml/System.Drawing.Drawing2D/Blend.xml @@ -41,22 +41,22 @@ Defines a blend pattern for a object. This class cannot be inherited. - and ) that each contain the same number of elements. Each element of the array represents a proportion of the distance along the gradient line. Each element of the array represents the proportion of the starting and ending colors in the gradient blend at the position along the gradient line represented by the corresponding element in the array. - - For example, if corresponding elements of the and arrays are 0.2 and 0.3, respectively, for a linear gradient from blue to red along a 100-pixel line, the color 20 pixels along that line (20 percent of the distance) consists of 30 percent blue and 70 percent red. - - - -## Examples - The following example is intended to be used in a Windows Forms environment. It demonstrates how to use the class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is blue on the left, blends to red in the center, and blends back to blue on the right. This is accomplished through the settings in the `myFactors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. - + and ) that each contain the same number of elements. Each element of the array represents a proportion of the distance along the gradient line. Each element of the array represents the proportion of the starting and ending colors in the gradient blend at the position along the gradient line represented by the corresponding element in the array. + + For example, if corresponding elements of the and arrays are 0.2 and 0.3, respectively, for a linear gradient from blue to red along a 100-pixel line, the color 20 pixels along that line (20 percent of the distance) consists of 30 percent blue and 70 percent red. + + + +## Examples + The following example is intended to be used in a Windows Forms environment. It demonstrates how to use the class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is blue on the left, blends to red in the center, and blends back to blue on the right. This is accomplished through the settings in the `myFactors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet3"::: + ]]> @@ -99,15 +99,15 @@ Initializes a new instance of the class. - class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is blue on the left, blends to red in the center, and blends back to blue on the right. This is accomplished through the settings in the `myFactors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. - + class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is blue on the left, blends to red in the center, and blends back to blue on the right. This is accomplished through the settings in the `myFactors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet3"::: + ]]> @@ -145,11 +145,11 @@ The number of elements in the and arrays. Initializes a new instance of the class with the specified number of factors and positions. - . - + . + ]]> @@ -197,20 +197,20 @@ Gets or sets an array of blend factors for the gradient. An array of blend factors that specify the percentages of the starting color and the ending color to be used at the corresponding position. - class by setting the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that imports the namespace. Handle the form's event and call the `DemonstrateBlend` method, passing `e` as . - + class by setting the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that imports the namespace. Handle the form's event and call the `DemonstrateBlend` method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet5"::: + ]]> @@ -258,20 +258,20 @@ Gets or sets an array of blend positions for the gradient. An array of blend positions that specify the percentages of distance along the gradient line. - class by setting the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that imports the namespace. Handle the form's event and call the `DemonstrateBlend` method, passing `e` as . - + class by setting the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that imports the namespace. Handle the form's event and call the `DemonstrateBlend` method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Drawing.Drawing2D/ColorBlend.xml b/xml/System.Drawing.Drawing2D/ColorBlend.xml index f708c454ef9..06407d08e50 100644 --- a/xml/System.Drawing.Drawing2D/ColorBlend.xml +++ b/xml/System.Drawing.Drawing2D/ColorBlend.xml @@ -84,7 +84,7 @@ class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is green on the left, blends to yellow, then to blue, and finally to red on the right. This is accomplished through the settings in the `myColors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. + The following example is intended to be used in a Windows Forms environment. It demonstrates how to use the class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is green on the left, blends to yellow, then to blue, and finally to red on the right. This is accomplished through the settings in the `myColors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet4"::: @@ -130,7 +130,7 @@ + For an example see ]]> diff --git a/xml/System.Drawing.Drawing2D/CustomLineCap.xml b/xml/System.Drawing.Drawing2D/CustomLineCap.xml index 7044ac50da5..841ffbe5217 100644 --- a/xml/System.Drawing.Drawing2D/CustomLineCap.xml +++ b/xml/System.Drawing.Drawing2D/CustomLineCap.xml @@ -126,7 +126,7 @@ ## Examples - The following example demonstrates how to use the constructor. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . + The following example demonstrates how to use the constructor. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet1"::: @@ -377,9 +377,9 @@ - Creates a object, `firstCap`,using the object just created. -- Creates a clone of `firstCap` by using the method. +- Creates a clone of `firstCap` by using the method. -- Sets up the and properties of the object, and uses that pen to draw a line and the custom caps to the screen. +- Sets up the and properties of the object, and uses that pen to draw a line and the custom caps to the screen. ```vb Public Sub CloneExample(e As PaintEventArgs) @@ -480,7 +480,7 @@ private void CloneExample(PaintEventArgs e) allows the resources used by this object to be reallocated for other purposes. + Calling allows the resources used by this object to be reallocated for other purposes. ]]> @@ -601,7 +601,7 @@ private void CloneExample(PaintEventArgs e) method. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet1"::: @@ -651,7 +651,7 @@ private void CloneExample(PaintEventArgs e) method. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste the code into a Windows Form. Handle the form's event and call `DrawCaps` from the form's event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet1"::: diff --git a/xml/System.Drawing.Drawing2D/DashStyle.xml b/xml/System.Drawing.Drawing2D/DashStyle.xml index 914172a66b2..0a260a18a8f 100644 --- a/xml/System.Drawing.Drawing2D/DashStyle.xml +++ b/xml/System.Drawing.Drawing2D/DashStyle.xml @@ -37,7 +37,7 @@ , set the property of the . + To define a custom , set the property of the . diff --git a/xml/System.Drawing.Drawing2D/GraphicsPath.xml b/xml/System.Drawing.Drawing2D/GraphicsPath.xml index f1ca33fab03..eb094ea8ad5 100644 --- a/xml/System.Drawing.Drawing2D/GraphicsPath.xml +++ b/xml/System.Drawing.Drawing2D/GraphicsPath.xml @@ -58,11 +58,11 @@ A path may be composed of any number of figures (subpaths). Each figure is either composed of a sequence of connected lines and curves or a geometric shape primitive. The starting point of a figure is the first point in the sequence of connected lines and curves. The ending point is the last point in the sequence. The starting and ending points of a geometric shape primitive are defined by the primitive specification. - A figure that consists of a sequence of connected lines and curves (whose starting and ending points may be coincident) is an open figure, unless it is closed explicitly. A figure can be closed explicitly, by using the method, which closes the current figure by connecting a line from the ending point to the starting point. A figure that consists of a geometric shape primitive is a closed figure. + A figure that consists of a sequence of connected lines and curves (whose starting and ending points may be coincident) is an open figure, unless it is closed explicitly. A figure can be closed explicitly, by using the method, which closes the current figure by connecting a line from the ending point to the starting point. A figure that consists of a geometric shape primitive is a closed figure. - For purposes of filling and clipping (for example, if a path is rendered using ), all open figures are closed by adding a line from the figure's first point to its last point. + For purposes of filling and clipping (for example, if a path is rendered using ), all open figures are closed by adding a line from the figure's first point to its last point. - A new figure is implicitly started when a path is created or when a figure is closed. A new figure is explicitly created when the method is called. + A new figure is implicitly started when a path is created or when a figure is closed. A new figure is explicitly created when the method is called. When a geometric shape primitive is added to a path, it adds a figure containing the geometric shape, and also implicitly starts a new figure. Consequently, there is always a current figure in a path. When lines and curves are added to a path, an implicit line is added as needed to connect the ending point of the current figure to the starting point of the new lines and curves to form a sequence of connected lines and curves. @@ -442,7 +442,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a rectangle, from which the arc is defined. @@ -510,7 +510,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -572,7 +572,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -634,7 +634,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -701,7 +701,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -759,7 +759,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -825,7 +825,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -903,7 +903,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -974,7 +974,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an array of seven points (representing two connected Bézier curves). @@ -1049,7 +1049,7 @@ ## Examples For an example see: - + ]]> @@ -1200,7 +1200,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1261,7 +1261,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1396,7 +1396,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an array of six points (representing a cardinal spline). @@ -1461,7 +1461,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1595,7 +1595,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1656,7 +1656,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1780,7 +1780,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1833,7 +1833,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1956,7 +1956,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an array of four points (representing a cardinal spline). @@ -1964,7 +1964,7 @@ - Draws the path to the screen. - Notice that while the array holds four points, there are only three segments, which is the number specified in the third argument of the call to . + Notice that while the array holds four points, there are only three segments, which is the number specified in the third argument of the call to . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet5"::: @@ -2027,7 +2027,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2081,7 +2081,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: Creates a bounding rectangle that defines an ellipse. @@ -2136,7 +2136,7 @@ . + For an example, see . ]]> @@ -2187,7 +2187,7 @@ . + For an example, see . ]]> @@ -2238,7 +2238,7 @@ . + For an example, see . ]]> @@ -2299,7 +2299,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2351,7 +2351,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2407,7 +2407,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a path, adds three lines that form a triangle, and then draws the path to the screen. + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a path, adds three lines that form a triangle, and then draws the path to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet7"::: @@ -2467,7 +2467,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2536,7 +2536,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an array of four points that describe a triangle. @@ -2609,7 +2609,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2739,7 +2739,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates two paths one a right-side-up triangle and the other an up-side-down triangle. @@ -2812,7 +2812,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2872,7 +2872,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a graphics path, adds the pie shape, and then draws the path to the screen. + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a graphics path, adds the pie shape, and then draws the path to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet10"::: @@ -2936,7 +2936,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -3005,7 +3005,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates an array of points that defines a polygon. @@ -3075,7 +3075,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -3212,7 +3212,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -3267,7 +3267,7 @@ . + For an example, see . ]]> @@ -3331,7 +3331,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -3397,7 +3397,7 @@ . + For an example, see . ]]> @@ -3614,7 +3614,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -3624,7 +3624,7 @@ - Draws the string to the screen. - There are two important things to be pointed out. First, notice that the `fontStyle` argument is cast as an integer. The method requires this so that two or more members can be combined to create the desired font style (in this case, and ). Secondly, notice that the method is used rather than the method. If is used, solid text is rendered, whereas if is used, the text will be an outline style. + There are two important things to be pointed out. First, notice that the `fontStyle` argument is cast as an integer. The method requires this so that two or more members can be combined to create the desired font style (in this case, and ). Secondly, notice that the method is used rather than the method. If is used, solid text is rendered, whereas if is used, the text will be an outline style. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet14"::: @@ -3691,7 +3691,7 @@ . + For an example, see . ]]> @@ -3754,7 +3754,7 @@ . + For an example, see . ]]> @@ -3817,7 +3817,7 @@ . + For an example, see . ]]> @@ -3859,14 +3859,14 @@ method to create a marker at the current location in a . Use the method to iterate through the existing markers in a path. + Use the method to create a marker at the current location in a . Use the method to iterate through the existing markers in a path. Markers are used to separate groups of subpaths. One or more subpaths can be contained between two markers. ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -3926,7 +3926,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -3938,7 +3938,7 @@ - Draws the new path to the screen. - Notice that the call the method must be cast as a . + Notice that the call the method must be cast as a . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet16"::: @@ -3984,7 +3984,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -4038,7 +4038,7 @@ `e`, an event object. The code creates a triangle by creating a new path, starting a figure, adding two intersecting lines to the figure, and then closing the figure to form a triangle. The path is then drawn to the screen. + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a triangle by creating a new path, starting a figure, adding two intersecting lines to the figure, and then closing the figure to form a triangle. The path is then drawn to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet18"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet18"::: @@ -4087,7 +4087,7 @@ allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. ]]> @@ -4214,7 +4214,7 @@ . + For an example, see . ]]> @@ -4266,7 +4266,7 @@ . + For an example, see . ]]> @@ -4314,7 +4314,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path and a translation matrix. @@ -4393,13 +4393,13 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path. - Adds an ellipse (circle) to it and draws it to the screen. -- Retrieves the bounding rectangle for the circle with a call to and draws the rectangle to the screen. +- Retrieves the bounding rectangle for the circle with a call to and draws the rectangle to the screen. - Creates a second graphics path. @@ -4572,7 +4572,7 @@ `e`, an event object. The code creates a path, adds a line to the path, and then gets the last point in the path. + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a path, adds a line to the path, and then gets the last point in the path. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet21"::: @@ -4704,7 +4704,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -4763,7 +4763,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -4826,7 +4826,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -4889,7 +4889,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -4944,7 +4944,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -4999,7 +4999,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -5064,7 +5064,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event. The code performs the following actions: - Creates a path. @@ -5072,7 +5072,7 @@ - Creates a wide pen and widens the path with that pen (to make the example clearer), -- Tests a point (100, 50) to see if it lies within (under) one of the edges of the rectangle by calling . +- Tests a point (100, 50) to see if it lies within (under) one of the edges of the rectangle by calling . The result is shown in the message box (in this case, true). In other words the edge is rendered over that point. @@ -5143,7 +5143,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -5256,7 +5256,7 @@ . + For an example, see . ]]> @@ -5364,7 +5364,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -5412,7 +5412,7 @@ . + For an example, see . ]]> @@ -5460,7 +5460,7 @@ . + For an example, see . ]]> @@ -5516,7 +5516,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path and adds an ellipse to the path. @@ -5582,7 +5582,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -5786,7 +5786,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -5846,7 +5846,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path and adds several primitives to the path. @@ -5900,14 +5900,14 @@ methods to iterate through the markers in the path. + This method creates a marker on the path that can be used to separate sections of the path. You can then use the methods to iterate through the markers in the path. Markers are used to separate groups of subpaths. One or more subpaths can be contained between two markers in the path. ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a path and adds several primitives to the path separated by markers, and draws the path to the screen. + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates a path and adds several primitives to the path separated by markers, and draws the path to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet26"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet26"::: @@ -5960,7 +5960,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path. @@ -6022,7 +6022,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path and adds an ellipse to the path. @@ -6098,7 +6098,7 @@ . + For an example, see . ]]> @@ -6162,7 +6162,7 @@ . + For an example, see . ]]> @@ -6228,7 +6228,7 @@ . + For an example, see . ]]> @@ -6290,7 +6290,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path and adds a rectangle to the path. @@ -6413,12 +6413,12 @@ , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . + This method creates an outline around the original lines in this , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . ## Examples - For an example, see . + For an example, see . ]]> @@ -6473,12 +6473,12 @@ , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . + This method creates an outline around the original lines in this , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . ## Examples - For an example, see . + For an example, see . ]]> @@ -6535,12 +6535,12 @@ , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . + This method creates an outline around the original lines in this , with a distance between the existing lines and the new outline equal to that of the width of the used in the call to . If you want to fill the space between the lines you must use the rather then the . ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a path and adds two ellipses to the path. @@ -6550,7 +6550,7 @@ - Draws the path in red. - Notice that the second rendering uses instead of , and hence the rendered figure has the outline filled. + Notice that the second rendering uses instead of , and hence the rendered figure has the outline filled. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicGraphicsPathExamples/CPP/form1.cpp" id="Snippet30"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/GraphicsPath/AddArc/form1.cs" id="Snippet30"::: diff --git a/xml/System.Drawing.Drawing2D/GraphicsPathIterator.xml b/xml/System.Drawing.Drawing2D/GraphicsPathIterator.xml index 4c244a5d733..75631916c1f 100644 --- a/xml/System.Drawing.Drawing2D/GraphicsPathIterator.xml +++ b/xml/System.Drawing.Drawing2D/GraphicsPathIterator.xml @@ -142,7 +142,7 @@ ## Examples - The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path. @@ -154,7 +154,7 @@ - Increments the path data index to the second marker. -- Calls the method to copy the path data contained between the start and end indexes to the points and types arrays. +- Calls the method to copy the path data contained between the start and end indexes to the points and types arrays. - Lists this copied data on the right side of the screen. @@ -325,7 +325,7 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path. @@ -337,7 +337,7 @@ - Increments the path data index to the second marker. -- Calls the method to copy the path data to the `points` and `types` arrays. +- Calls the method to copy the path data to the `points` and `types` arrays. - Lists this copied data on the right side of the screen. @@ -457,14 +457,14 @@ ## Remarks All curves in a path are stored as sequences of Bézier splines. For example, when you add an ellipse to a path, you specify the upper-left corner, the width, and the height of the ellipse's bounding rectangle. Those numbers (upper-left corner, width, and height) are not stored in the path; instead; the ellipse is converted to a sequence of four Bézier splines. The path stores the endpoints and control points of those Bézier splines. - A path stores an array of data points, each of which belongs to a line or a Bézier spline. If some of the points in the array belong to Bézier splines, then returns `true`. If all points in the array belong to lines, then returns `false`. + A path stores an array of data points, each of which belongs to a line or a Bézier spline. If some of the points in the array belong to Bézier splines, then returns `true`. If all points in the array belong to lines, then returns `false`. - Certain methods flatten a path, which means that all the curves in the path are converted to sequences of lines. After a path has been flattened, will always return `false`. Calling the , , or method of the class will flatten a path. + Certain methods flatten a path, which means that all the curves in the path are converted to sequences of lines. After a path has been flattened, will always return `false`. Calling the , , or method of the class will flatten a path. ## Examples - The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object, `myPath`. @@ -533,12 +533,12 @@ method to set markers in a path. Markers are used to create groups of subpaths. One or more subpaths can be between two markers. + Use the method to set markers in a path. Markers are used to create groups of subpaths. One or more subpaths can be between two markers. ## Examples - The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object. @@ -550,7 +550,7 @@ - Creates a object, `myPathSection`, to receive copied points. -- Calls the method, which iterates to the first marker and copies all the points contained between that marker and the next to `myPathSection`. +- Calls the method, which iterates to the first marker and copies all the points contained between that marker and the next to `myPathSection`. - Returns the number of points copied to `markerPoints`. @@ -606,12 +606,12 @@ method to set markers in a path. Markers are used to create groups of subpaths. One or more subpaths can be between two markers. + Use the method to set markers in a path. Markers are used to create groups of subpaths. One or more subpaths can be between two markers. ## Examples - The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object. @@ -621,9 +621,9 @@ - Creates a object. -- Calls the method. +- Calls the method. -- Uses the values returned from the iterative calls to to draw the start and stop points for each marker to the screen. +- Uses the values returned from the iterative calls to to draw the start and stop points for each marker to the screen. - Draws the value for the total number of points to the screen. @@ -679,7 +679,7 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object. @@ -689,7 +689,7 @@ - Creates a and rewinds it. -- In a `for` loop, iterates through the points using the and methods. +- In a `for` loop, iterates through the points using the and methods. - Uses the values returned from the iterative calls to list the subpath number, the number of points in it, and the type of the path points to the right side of the screen. @@ -756,7 +756,7 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object. @@ -768,7 +768,7 @@ - Creates a object, `myPathSection`, to receive copied points. -- Calls the method, which iterates to the third subpath (figure) and copies all the points contained in that subpath to the `myPathSection` path, and also returns the number of points copied to `subpathPoints`. +- Calls the method, which iterates to the third subpath (figure) and copies all the points contained in that subpath to the `myPathSection` path, and also returns the number of points copied to `subpathPoints`. - Lists the subpath number and number of points it contains to the right side of the screen. @@ -824,7 +824,7 @@ `e`, an event object. The code performs the following actions: + The following example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a object. @@ -834,9 +834,9 @@ - Creates a object. -- Calls the method. +- Calls the method. -- Uses the values returned from the iterative calls to to draw the start and stop values for each subpath to the screen. +- Uses the values returned from the iterative calls to to draw the start and stop values for each subpath to the screen. - Draws the value for the total number of subpaths to the screen. @@ -884,7 +884,7 @@ method of an iterator, it gets the first figure (subpath) of that iterator's associated path. The second time, it gets the second figure, and so on. When you call the method, the sequence starts over; that is, after you call , the next call to gets the first figure in the path. The and methods behave similarly. + The first time you call the method of an iterator, it gets the first figure (subpath) of that iterator's associated path. The second time, it gets the second figure, and so on. When you call the method, the sequence starts over; that is, after you call , the next call to gets the first figure in the path. The and methods behave similarly. ]]> diff --git a/xml/System.Drawing.Drawing2D/HatchBrush.xml b/xml/System.Drawing.Drawing2D/HatchBrush.xml index 4dc84e0c903..3bd4699b946 100644 --- a/xml/System.Drawing.Drawing2D/HatchBrush.xml +++ b/xml/System.Drawing.Drawing2D/HatchBrush.xml @@ -38,7 +38,7 @@ , which fills the background and one for the lines that form the pattern over the background defined by the property. The property defines what type of pattern the brush has and can be any value from the enumeration. There are more than fifty elements in the enumeration. + A hatch pattern is made from two colors: one defined by the , which fills the background and one for the lines that form the pattern over the background defined by the property. The property defines what type of pattern the brush has and can be any value from the enumeration. There are more than fifty elements in the enumeration. The following illustration shows an ellipse filled with a horizontal hatch pattern. @@ -156,7 +156,7 @@ ## Examples - The following example shows how to use the to create the shown in the previous illustration. + The following example shows how to use the to create the shown in the previous illustration. :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/HatchBrush/Overview/Class1.cs" id="Snippet41"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/HatchBrush/Overview/Class1.vb" id="Snippet41"::: diff --git a/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml b/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml index 06dfab8ca07..9740ca7dd69 100644 --- a/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml +++ b/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml @@ -48,7 +48,7 @@ All linear gradients are defined along a line specified either by the width of a rectangle or by two points. - By default, a two-color linear gradient is an even horizontal linear blend from the starting color to the ending color along the specified line. Customize the blend pattern using the class, the methods, or the methods. Customize the direction of the gradient by specifying the enumeration or the angle in the constructor. + By default, a two-color linear gradient is an even horizontal linear blend from the starting color to the ending color along the specified line. Customize the blend pattern using the class, the methods, or the methods. Customize the direction of the gradient by specifying the enumeration or the angle in the constructor. Use the property to create a multicolor gradient. @@ -558,7 +558,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . @@ -760,7 +760,7 @@ . + For an example, see . ]]> @@ -807,13 +807,13 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . - Draws an ellipse to the screen using this brush. -- Calls the method, to transform the . +- Calls the method, to transform the . - Draws an ellipse to the screen directly below the first ellipse, using the transformed brush. @@ -911,13 +911,13 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . - Draws an ellipse to the screen using this brush. -- Calls the method to transform the . +- Calls the method to transform the . - Draws an ellipse to the screen directly below the first ellipse, using the transformed brush. @@ -925,7 +925,7 @@ - Draws a third ellipse to the screen below the first two. - Notice that the lowest ellipse is drawn the same size as the first, and that, due to the call to the method, the gradient has been reduced to match. + Notice that the lowest ellipse is drawn the same size as the first, and that, due to the call to the method, the gradient has been reduced to match. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicLinearGradientBrush/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/LinearGradientBrush/Clone/form1.cs" id="Snippet3"::: @@ -989,7 +989,7 @@ . + For an example, see . ]]> @@ -1036,17 +1036,17 @@ `e`, an event object. The code + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code - Creates a new . - Draws an ellipse to the screen using this brush. -- Rotates the 45 degrees by calling the method. +- Rotates the 45 degrees by calling the method. - Draws an ellipse to the screen directly below the first ellipse, using the rotated brush. - Notice that the gradient of the lower ellipse is at a 45 degree angle to the x-axis of the top ellipse. Also notice that a call to the method is used to justify the left edge of the gradient fill with the left edge of the lower ellipse. + Notice that the gradient of the lower ellipse is at a 45 degree angle to the x-axis of the top ellipse. Also notice that a call to the method is used to justify the left edge of the gradient fill with the left edge of the lower ellipse. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicLinearGradientBrush/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/LinearGradientBrush/Clone/form1.cs" id="Snippet4"::: @@ -1112,7 +1112,7 @@ . + For an example, see . ]]> @@ -1161,7 +1161,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . @@ -1171,7 +1171,7 @@ - Draws an ellipse to the screen directly below the first ellipse, using the scaled brush. - Notice that the gradient of the lower ellipse is stretched by a factor of two. Also notice that a call to the method is used to justify the left edge of the gradient fill with the left edge of ellipse. + Notice that the gradient of the lower ellipse is stretched by a factor of two. Also notice that a call to the method is used to justify the left edge of the gradient fill with the left edge of ellipse. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicLinearGradientBrush/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/LinearGradientBrush/Clone/form1.cs" id="Snippet5"::: @@ -1240,7 +1240,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1292,7 +1292,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . @@ -1371,7 +1371,7 @@ ## Examples - For an example, see `.` + For an example, see `.` ]]> @@ -1423,7 +1423,7 @@ ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . @@ -1551,7 +1551,7 @@ . + For an example, see . ]]> @@ -1600,7 +1600,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a new . diff --git a/xml/System.Drawing.Drawing2D/Matrix.xml b/xml/System.Drawing.Drawing2D/Matrix.xml index 676214787d1..5c262314468 100644 --- a/xml/System.Drawing.Drawing2D/Matrix.xml +++ b/xml/System.Drawing.Drawing2D/Matrix.xml @@ -717,7 +717,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -994,7 +994,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -1117,7 +1117,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); and the method to rotate a string. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `DrawVerticalStringFromBottomUp` method in the form's event handler, passing `e` as . + The following code example demonstrates using a and the method to rotate a string. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `DrawVerticalStringFromBottomUp` method in the form's event handler, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet5"::: @@ -1180,7 +1180,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); - Draws the transformed rectangle to the screen (the red rectangle). - Notice that the red rectangle has been rotated around the upper left-hand corner of the rectangle (the rotation point specified the method). + Notice that the red rectangle has been rotated around the upper left-hand corner of the rectangle (the rotation point specified the method). :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMatrixExamples/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/Matrix/Multiply/form1.cs" id="Snippet4"::: @@ -1246,7 +1246,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -1380,7 +1380,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); - Draws an ellipse using a blue pen. - The result is a green rectangle, a red parallelogram and a transformed, blue ellipse. Notice that the green rectangle (drawn prior to setting the transform) directly uses the coordinates supplied in the call. The other two figures are transformed prior to drawing. The rectangle is transformed to a parallelogram (red), and the ellipse (blue) is transformed to fit into the transformed parallelogram. Notice the bottom of the rectangle is moved (sheared) in the x-axis by a factor of two times the height of the rectangle, thus forming the parallelogram. + The result is a green rectangle, a red parallelogram and a transformed, blue ellipse. Notice that the green rectangle (drawn prior to setting the transform) directly uses the coordinates supplied in the call. The other two figures are transformed prior to drawing. The rectangle is transformed to a parallelogram (red), and the ellipse (blue) is transformed to fit into the transformed parallelogram. Notice the bottom of the rectangle is moved (sheared) in the x-axis by a factor of two times the height of the rectangle, thus forming the parallelogram. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMatrixExamples/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/Matrix/Multiply/form1.cs" id="Snippet6"::: @@ -1438,7 +1438,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); ## Examples - For an example, see . + For an example, see . ]]> @@ -1573,7 +1573,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -1794,7 +1794,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -1938,7 +1938,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> diff --git a/xml/System.Drawing.Drawing2D/PathGradientBrush.xml b/xml/System.Drawing.Drawing2D/PathGradientBrush.xml index b76c1c363eb..9b83bc4eb67 100644 --- a/xml/System.Drawing.Drawing2D/PathGradientBrush.xml +++ b/xml/System.Drawing.Drawing2D/PathGradientBrush.xml @@ -738,7 +738,7 @@ . + For an example, see . ]]> @@ -785,7 +785,7 @@ `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path and adds a rectangle to it. @@ -797,7 +797,7 @@ - Creates s matrix that rotates the brush 90 degrees and translates it by 100 in both axes. -- Applies this matrix to the brush by using the method. +- Applies this matrix to the brush by using the method. - Draws the brush to the screen. @@ -951,7 +951,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); . + For an example, see . ]]> @@ -998,7 +998,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path and adds a rectangle to it. @@ -1008,7 +1008,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); - Draws the to the screen prior to applying the rotate transform. -- Applies the rotate transform to the brush by using its method. +- Applies the rotate transform to the brush by using its method. - Draws the rotated brush (rectangle) to the screen. @@ -1078,7 +1078,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); . + For an example, see . ]]> @@ -1127,7 +1127,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); `e`, an event object. The code + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code - Creates a graphics path and adds a rectangle to it. @@ -1137,9 +1137,9 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); - Draws the to the screen prior to applying the scale transform. -- Applies the scale transform to the brush by using its method. +- Applies the scale transform to the brush by using its method. -- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. +- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. - Draws the translated brush rectangle to the screen. @@ -1207,12 +1207,12 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); array, the first color in the array is used for the ending color. The colors specified in this array are used for discrete points on the brush's boundary path. + If there is more than one color in the array, the first color in the array is used for the ending color. The colors specified in this array are used for discrete points on the brush's boundary path. ## Examples - For an example, see `.` + For an example, see `.` ]]> @@ -1259,14 +1259,14 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. + If there is more than one color in the array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. By default, as you move from the boundary of a path gradient to the center point, the color changes gradually from the boundary color to the center color. You can customize the positioning and blending of the boundary and center colors by calling this method. ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path and adds a rectangle to it. @@ -1276,9 +1276,9 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); - Draws the to the screen prior to applying the blend transform. -- Applies the blend transform to the brush by using its method. +- Applies the blend transform to the brush by using its method. -- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. +- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. - Draws the transformed-brush rectangle is drawn to the screen. @@ -1346,14 +1346,14 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. + If there is more than one color in the array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. By default, as you move from the boundary of a path gradient to the center point, the color changes gradually from the boundary color to the center color. You can customize the positioning and blending of the boundary and center colors by calling this method. ## Examples - For an example, see . + For an example, see . ]]> @@ -1400,14 +1400,14 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. + If there is more than one color in the array, the first color in the array is used for the ending color. The colors specified in this array are colors used for discrete points on the brush's boundary path. By default, as you move from the boundary of a path gradient to the center point, the color changes gradually from the boundary color to the center color. You can customize the positioning and blending of the boundary and center colors by calling this method. ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, an event object. The code performs the following actions: - Creates a graphics path and adds a rectangle to it. @@ -1417,9 +1417,9 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); - Draws the to the screen prior to applying the blend transform. -- Applies the blend transform to the brush by using its method. +- Applies the blend transform to the brush by using its method. -- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. +- Calls the method to move the brush rectangle such that it does not overlay the one drawn to the screen earlier. - Draws the transformed-brush rectangle to the screen. @@ -1479,7 +1479,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); in the array corresponds to a point in the path. + Each in the array corresponds to a point in the path. ]]> @@ -1593,7 +1593,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); . + For an example, see . ]]> @@ -1642,7 +1642,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); . + For an example, see . ]]> diff --git a/xml/System.Drawing.Drawing2D/RegionData.xml b/xml/System.Drawing.Drawing2D/RegionData.xml index 99705615091..75eb837e5b9 100644 --- a/xml/System.Drawing.Drawing2D/RegionData.xml +++ b/xml/System.Drawing.Drawing2D/RegionData.xml @@ -109,7 +109,7 @@ ## Examples -- The following example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the `Paint` event handler. The code example demonstrates how to use the from one object to set the for another . +- The following example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the `Paint` event handler. The code example demonstrates how to use the from one object to set the for another . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet13"::: diff --git a/xml/System.Drawing.Drawing2D/WarpMode.xml b/xml/System.Drawing.Drawing2D/WarpMode.xml index ea572e41ff9..92c3601210a 100644 --- a/xml/System.Drawing.Drawing2D/WarpMode.xml +++ b/xml/System.Drawing.Drawing2D/WarpMode.xml @@ -34,11 +34,11 @@ Specifies the type of warp transformation applied in a method. - method to warp or distort the figures in a graphics path. This can be used to create unusual shapes. - + method to warp or distort the figures in a graphics path. This can be used to create unusual shapes. + ]]> diff --git a/xml/System.Drawing.Drawing2D/WrapMode.xml b/xml/System.Drawing.Drawing2D/WrapMode.xml index ce4c5f8f0c8..d851f8a78c3 100644 --- a/xml/System.Drawing.Drawing2D/WrapMode.xml +++ b/xml/System.Drawing.Drawing2D/WrapMode.xml @@ -34,20 +34,20 @@ Specifies how a texture or gradient is tiled when it is smaller than the area being filled. - enumeration values have on a tiled image, see [How to: Tile a Shape with an Image](/dotnet/framework/winforms/advanced/how-to-tile-a-shape-with-an-image). - - - -## Examples - The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a and the enumeration. This example is designed to be used with Windows Forms. Create a form containing a button named `Button2`. Paste the code into the form and associate the `Button2_Click` method with the button's event. - + enumeration values have on a tiled image, see [How to: Tile a Shape with an Image](/dotnet/framework/winforms/advanced/how-to-tile-a-shape-with-an-image). + + + +## Examples + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a and the enumeration. This example is designed to be used with Windows Forms. Create a form containing a button named `Button2`. Paste the code into the form and associate the `Button2_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet2"::: + ]]> How To: Tile a Shape with an Image diff --git a/xml/System.Drawing.Imaging/BitmapData.xml b/xml/System.Drawing.Imaging/BitmapData.xml index 132bd61755d..9b5563a7f1a 100644 --- a/xml/System.Drawing.Imaging/BitmapData.xml +++ b/xml/System.Drawing.Imaging/BitmapData.xml @@ -36,15 +36,15 @@ Specifies the attributes of a bitmap image. The class is used by the and methods of the class. Not inheritable. - class with the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . - + class with the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: + ]]> @@ -170,11 +170,11 @@ Gets or sets the format of the pixel information in the object that returned this object. A that specifies the format of the pixel information in the associated object. - @@ -267,18 +267,18 @@ Gets or sets the address of the first pixel data in the bitmap. This can also be thought of as the first scan line in the bitmap. The address of the first pixel data in the bitmap. - , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's Paint event by calling the `LockUnlockBitsExample` method, passing `e` as . - + , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's Paint event by calling the `LockUnlockBitsExample` method, passing `e` as . + > [!NOTE] -> The following example code was created for use with an image with the format. - +> The following example code was created for use with an image with the format. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: + ]]> @@ -326,11 +326,11 @@ Gets or sets the stride width (also called scan width) of the object. The stride width, in bytes, of the object. - diff --git a/xml/System.Drawing.Imaging/ColorMatrix.xml b/xml/System.Drawing.Imaging/ColorMatrix.xml index a6e4a6e362d..1de373fcf76 100644 --- a/xml/System.Drawing.Imaging/ColorMatrix.xml +++ b/xml/System.Drawing.Imaging/ColorMatrix.xml @@ -78,9 +78,9 @@ 1. Initialize a object. -2. Create an object and pass the object to the method of the object. +2. Create an object and pass the object to the method of the object. -3. Pass the object to the method of a object. +3. Pass the object to the method of a object. The preceding example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler diff --git a/xml/System.Drawing.Imaging/EncoderParameter.xml b/xml/System.Drawing.Imaging/EncoderParameter.xml index ca5d8d69d71..feaa522c940 100644 --- a/xml/System.Drawing.Imaging/EncoderParameter.xml +++ b/xml/System.Drawing.Imaging/EncoderParameter.xml @@ -54,7 +54,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates how to create a using the constructor. To run this example, paste the code into a Windows Form and call the `VaryQualityLevel` method from the form's constructor. This example requires an image file named `TestPhoto.jpg` located at **c:\\**. + The following code example demonstrates how to create a using the constructor. To run this example, paste the code into a Windows Form and call the `VaryQualityLevel` method from the form's constructor. This example requires an image file named `TestPhoto.jpg` located at **c:\\**. :::code language="csharp" source="~/snippets/csharp/System.Drawing.Imaging/EncoderParameter/Overview/Form1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Imaging/EncoderParameter/Overview/Form1.vb" id="Snippet8"::: @@ -261,7 +261,7 @@ using the constructor. To run this example, paste the code into a Windows Form and call the `VaryQualityLevel` method from the form's constructor. This example requires an image file named `TestPhoto.jpg` located at **c:\\**. + The following code example demonstrates how to create a using the constructor. To run this example, paste the code into a Windows Form and call the `VaryQualityLevel` method from the form's constructor. This example requires an image file named `TestPhoto.jpg` located at **c:\\**. :::code language="csharp" source="~/snippets/csharp/System.Drawing.Imaging/EncoderParameter/Overview/Form1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Imaging/EncoderParameter/Overview/Form1.vb" id="Snippet8"::: @@ -814,7 +814,7 @@ allows the resources used by this object to be reallocated for other purposes. + Calling allows the resources used by this object to be reallocated for other purposes. ]]> diff --git a/xml/System.Drawing.Imaging/EncoderParameterValueType.xml b/xml/System.Drawing.Imaging/EncoderParameterValueType.xml index 87bd41e1c58..7f57374113a 100644 --- a/xml/System.Drawing.Imaging/EncoderParameterValueType.xml +++ b/xml/System.Drawing.Imaging/EncoderParameterValueType.xml @@ -37,9 +37,9 @@ objects to various file formats. Image encoders are built into GDI+ for the BMP, JPEG, GIF, TIFF, and PNG formats. An encoder is invoked when you call the or method of a object. + GDI+ uses image encoders to convert the images stored in objects to various file formats. Image encoders are built into GDI+ for the BMP, JPEG, GIF, TIFF, and PNG formats. An encoder is invoked when you call the or method of a object. - The data member of the object indicates the length of the character string including the `null` terminator. + The data member of the object indicates the length of the character string including the `null` terminator. ]]> diff --git a/xml/System.Drawing.Imaging/EncoderParameters.xml b/xml/System.Drawing.Imaging/EncoderParameters.xml index c774c80bd61..5f0de9b75e8 100644 --- a/xml/System.Drawing.Imaging/EncoderParameters.xml +++ b/xml/System.Drawing.Imaging/EncoderParameters.xml @@ -97,7 +97,7 @@ and methods receive an object as an argument. The method returns an object. + Some of the and methods receive an object as an argument. The method returns an object. diff --git a/xml/System.Drawing.Imaging/EncoderValue.xml b/xml/System.Drawing.Imaging/EncoderValue.xml index 0c414714409..18fd6f8f0c4 100644 --- a/xml/System.Drawing.Imaging/EncoderValue.xml +++ b/xml/System.Drawing.Imaging/EncoderValue.xml @@ -34,11 +34,11 @@ Used to specify the parameter value passed to a JPEG or TIFF image encoder when using the or methods. - or method of an object, you can pass parameters to the image encoder by passing an object to the or method. An object contains an array of objects. Each object has an array of values and an property that specifies the parameter category. The enumeration provides names for some of the values that can be passed to the JPEG and TIFF image encoders. - + or method of an object, you can pass parameters to the image encoder by passing an object to the or method. An object contains an array of objects. Each object has an array of values and an property that specifies the parameter category. The enumeration provides names for some of the values that can be passed to the JPEG and TIFF image encoders. + ]]> diff --git a/xml/System.Drawing.Imaging/ImageAttributes.xml b/xml/System.Drawing.Imaging/ImageAttributes.xml index 5db3cb1f4c3..e05bb6f0713 100644 --- a/xml/System.Drawing.Imaging/ImageAttributes.xml +++ b/xml/System.Drawing.Imaging/ImageAttributes.xml @@ -52,7 +52,7 @@ object maintains several color-adjustment settings, including color-adjustment matrices, grayscale-adjustment matrices, gamma-correction values, color-map tables, and color-threshold values. During rendering, colors can be corrected, darkened, lightened, and removed. To apply such manipulations, initialize an object and pass the path of that object (along with the path of an ) to the method. + An object maintains several color-adjustment settings, including color-adjustment matrices, grayscale-adjustment matrices, gamma-correction values, color-map tables, and color-threshold values. During rendering, colors can be corrected, darkened, lightened, and removed. To apply such manipulations, initialize an object and pass the path of that object (along with the path of an ) to the method. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -67,9 +67,9 @@ 1. Initialize a object. -2. Create an object and pass the object to the method of the object. +2. Create an object and pass the object to the method of the object. -3. Pass the object to the method of a object. +3. Pass the object to the method of a object. :::code language="csharp" source="~/snippets/csharp/System.Drawing.Imaging/ColorMatrix/Overview/Class1.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Imaging/ColorMatrix/Overview/Class1.vb" id="Snippet21"::: @@ -157,7 +157,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the brush category, the default settings apply to the brush category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a default remap table that converts red to green, and you specify a default gamma value of 1.8. If you call the method, the default remap table (red to green) and the default gamma value (1.8) will not apply to brushes. If you later call the method, the brush category will not revert to the default remap table; rather, the brush category will have no remap table. Similarly, the brush category will not revert to the default gamma value; rather, the brush category will have no gamma value. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a default remap table that converts red to green, and you specify a default gamma value of 1.8. If you call the method, the default remap table (red to green) and the default gamma value (1.8) will not apply to brushes. If you later call the method, the brush category will not revert to the default remap table; rather, the brush category will have no remap table. Similarly, the brush category will not revert to the default gamma value; rather, the brush category will have no gamma value. ]]> @@ -265,7 +265,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a default color key that makes any color with a red component from 200 through 255 transparent, and you specify a default gamma value of 1.8. If you set the color key of the pen category by calling the method, the default color key and the default gamma value will not apply to pens. If you later clear the pen color key by calling the method, the pen category will not revert to the default color key; rather, the pen category will have no color key. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a default color key that makes any color with a red component from 200 through 255 transparent, and you specify a default gamma value of 1.8. If you set the color key of the pen category by calling the method, the default color key and the default gamma value will not apply to pens. If you later clear the pen color key by calling the method, the pen category will not revert to the default color key; rather, the pen category will have no color key. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. ]]> @@ -373,7 +373,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a color-adjustment matrix and a gamma value for the default category. If you set a color-adjustment matrix for the pen category by calling the method, the default color-adjustment matrix will not apply to pens. If you later clear the pen color-adjustment matrix by calling the method, the pen category will not revert to the default adjustment matrix; rather, the pen category will have no adjustment matrix. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a color-adjustment matrix and a gamma value for the default category. If you set a color-adjustment matrix for the pen category by calling the method, the default color-adjustment matrix will not apply to pens. If you later clear the pen color-adjustment matrix by calling the method, the pen category will not revert to the default adjustment matrix; rather, the pen category will have no adjustment matrix. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. ]]> @@ -481,7 +481,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a gamma value and a color-adjustment matrix for the default category. If you set the gamma value for the pen category by calling the method, the default gamma value will not apply to pens. If you later clear the pen gamma value by calling the method, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. Similarly, the pen category will not revert to the default color-adjustment matrix; rather, the pen category will have no color-adjustment matrix. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a gamma value and a color-adjustment matrix for the default category. If you set the gamma value for the pen category by calling the method, the default gamma value will not apply to pens. If you later clear the pen gamma value by calling the method, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. Similarly, the pen category will not revert to the default color-adjustment matrix; rather, the pen category will have no color-adjustment matrix. ]]> @@ -540,7 +540,7 @@ ## Remarks An object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a gamma value for the default category, a different gamma value for the bitmap category, and still a different gamma value for the pen category. - You can disable color adjustment for the default category by calling the method. Later, you can reinstate color adjustment for the default category by calling the method. The color adjustment then returns to what was in place before the call to . + You can disable color adjustment for the default category by calling the method. Later, you can reinstate color adjustment for the default category by calling the method. The color adjustment then returns to what was in place before the call to . ]]> @@ -587,7 +587,7 @@ ## Remarks An object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a gamma value for the default category, a different gamma value for the bitmap category, and still a different gamma value for the pen category. - You can disable color adjustment for a certain category by calling the method. Later, you can reinstate color adjustment for that category by calling the method. The color adjustment then returns to what was in place before the call to . + You can disable color adjustment for a certain category by calling the method. Later, you can reinstate color adjustment for that category by calling the method. The color adjustment then returns to what was in place before the call to . ]]> @@ -695,7 +695,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, the default settings apply to the bitmap category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel and an adjustment matrix for the default category. If you set the output channel for the bitmap category by calling the method, the default output channel will not apply to bitmaps. If you later clear the bitmap output channel by calling the method, the bitmap category will not revert to the default output channel; rather, the bitmap category will have no output channel setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel and an adjustment matrix for the default category. If you set the output channel for the bitmap category by calling the method, the default output channel will not apply to bitmaps. If you later clear the bitmap output channel by calling the method, the bitmap category will not revert to the default output channel; rather, the bitmap category will have no output channel setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix. ]]> @@ -803,7 +803,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, the default settings apply to the bitmap category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel profile and an adjustment matrix for the default category. If you set the output channel profile for the bitmap category by calling the method, the default output channel profile will not apply to bitmaps. If you later clear the bitmap output channel profile by calling the method, the bitmap category will not revert to the default output channel profile; rather, the bitmap category will have no output channel profile setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel profile and an adjustment matrix for the default category. If you set the output channel profile for the bitmap category by calling the method, the default output channel profile will not apply to bitmaps. If you later clear the bitmap output channel profile by calling the method, the bitmap category will not revert to the default output channel profile; rather, the bitmap category will have no output channel profile setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix. ]]> @@ -911,7 +911,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a remap table and a gamma value for the default category. If you set the remap table for the pen category by calling the method, the default remap table will not apply to pens. If you later clear the pen remap table by calling the method, the pen category will not revert to the default remap table; rather, the pen category will have no remap table. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a remap table and a gamma value for the default category. If you set the remap table for the pen category by calling the method, the default remap table will not apply to pens. If you later clear the pen remap table by calling the method, the pen category will not revert to the default remap table; rather, the pen category will have no remap table. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. ]]> @@ -1023,7 +1023,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a threshold and a gamma value for the default category. If you set the threshold for the pen category by calling the method, the default threshold will not apply to pens. If you later clear the pen threshold by calling the method, the pen category will not revert to the default threshold; rather, the pen category will have no threshold. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a threshold and a gamma value for the default category. If you set the threshold for the pen category by calling the method, the default threshold will not apply to pens. If you later clear the pen threshold by calling the method, the pen category will not revert to the default threshold; rather, the pen category will have no threshold. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. ]]> @@ -1107,10 +1107,10 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -1194,7 +1194,7 @@ ## Remarks An object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color-remap table for the default category, a different color-remap table for the bitmap category, and still a different color-remap table for the pen category. - When you call the method, you can specify the adjustment category that is used to adjust the palette colors. For example, if you pass to the method, the adjustment settings of the bitmap category are used to adjust the palette colors. + When you call the method, you can specify the adjustment category that is used to adjust the palette colors. For example, if you pass to the method, the adjustment settings of the bitmap category are used to adjust the palette colors. ]]> @@ -1257,7 +1257,7 @@ ## Remarks A color-remap table is an array of structures. Each structure has two objects: one that specifies an old color and one that specifies a corresponding new color. During rendering, any color that matches one of the old colors in the remap table is changed to the corresponding new color. - Calling the method has the same effect as passing to the method. The specified remap table applies to items in metafiles that are filled with a brush. + Calling the method has the same effect as passing to the method. The specified remap table applies to items in metafiles that are filled with a brush. This method is intended to be used only with metafiles. @@ -1433,7 +1433,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -1488,7 +1488,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color key for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color key for the pen category by passing to the method, none of the default adjustment settings will apply to pens. @@ -1497,7 +1497,7 @@ 1. Opens an that uses the file Circle.bmp and draws it to the screen. -2. Creates an object and sets its color key by calling the method. +2. Creates an object and sets its color key by calling the method. 3. Draws the image to the screen using the color key of the object. @@ -1577,7 +1577,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix, not the grayscale-adjustment matrix. Therefore, the grayscale-adjustment matrix passed to this method has no effect. + Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix, not the grayscale-adjustment matrix. Therefore, the grayscale-adjustment matrix passed to this method has no effect. ]]> @@ -1705,7 +1705,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment and grayscale-adjustment matrices for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment and grayscale-adjustment matrices for the pen category by passing to the method, none of the default adjustment settings will apply to pens. ]]> @@ -1769,7 +1769,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix + Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix @@ -1780,7 +1780,7 @@ 2. Creates a and sets its location to 1.75, which emphasizes the red component of the image. -3. Creates an object and calls the method. +3. Creates an object and calls the method. 4. Draws the image (a second rectangle) to the screen using the just set in the object. @@ -1849,7 +1849,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -1903,12 +1903,12 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment matrix for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment matrix for the pen category by passing to the method, none of the default adjustment settings will apply to pens. ## Examples - The following code example demonstrates how to use the method. To run this example, paste the code into a Windows Form and call `RotateColors` from the form's event-handling method, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste the code into a Windows Form and call `RotateColors` from the form's event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing.Imaging/ColorMatrix/.ctor/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Imaging/ColorMatrix/.ctor/Form1.vb" id="Snippet1"::: @@ -1986,7 +1986,7 @@ 1. Opens an that uses the file Camera.jpg and draws it to the screen using the default value for gamma. -2. Creates an object and sets its gamma to 2.2 by calling the method. +2. Creates an object and sets its gamma to 2.2 by calling the method. 3. Draws the image (a second camera) to the screen using the gamma value just set in the object. @@ -2045,14 +2045,14 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the gamma value for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the gamma value for the pen category by passing to the method, none of the default adjustment settings will apply to pens. Gamma values outside the usual range may be useful for old CRT monitors or for monitors that are in unusual lighting conditions, such as industrial environments or window displays. ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2124,9 +2124,9 @@ 3. Draws the image to the screen. -4. Calls the method. +4. Calls the method. -5. Draws the image (a second camera) to the screen; however, because the method was called, the gamma setting defaults to a value of 1.0 and the image is drawn to the screen with the default gamma setting. +5. Draws the image (a second camera) to the screen; however, because the method was called, the gamma setting defaults to a value of 1.0 and the image is drawn to the screen with the default gamma setting. Note that the image on the left is very washed out (gamma of 0.25) and the image on the right has more contrast (gamma of 1.0). @@ -2242,7 +2242,7 @@ method to convert an image to a CMYK color space and examine the intensities of one of the CMYK color channels. For example, suppose you create an object and set its bitmap output channel to . If you pass the path of that object to the method, the cyan component of each pixel is calculated, and each pixel in the rendered image is a shade of gray that indicates the intensity of its cyan channel. Similarly, you can render images that indicate the intensities of the magenta, yellow, and black channels. + You can use the method to convert an image to a CMYK color space and examine the intensities of one of the CMYK color channels. For example, suppose you create an object and set its bitmap output channel to . If you pass the path of that object to the method, the cyan component of each pixel is calculated, and each pixel in the rendered image is a shade of gray that indicates the intensity of its cyan channel. Similarly, you can render images that indicate the intensities of the magenta, yellow, and black channels. An object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel for the default category and a different output channel for the bitmap category. @@ -2251,7 +2251,7 @@ ## Examples - The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `ShowOutputChannels`, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `ShowOutputChannels`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet4"::: @@ -2301,18 +2301,18 @@ method to convert an image to a CMYK color space and examine the intensities of one of the CMYK color channels. For example, suppose you create an object and set its bitmap output channel to . If you pass the path of that object to the method, the cyan component of each pixel is calculated, and each pixel in the rendered image is a shade of gray that indicates the intensity of its cyan channel. Similarly, you can render images that indicate the intensities of the magenta, yellow, and black channels. + You can use the method to convert an image to a CMYK color space and examine the intensities of one of the CMYK color channels. For example, suppose you create an object and set its bitmap output channel to . If you pass the path of that object to the method, the cyan component of each pixel is calculated, and each pixel in the rendered image is a shade of gray that indicates the intensity of its cyan channel. Similarly, you can render images that indicate the intensities of the magenta, yellow, and black channels. An object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel for the default category and a different output channel for the bitmap category. The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, the default settings apply to the bitmap category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel for the bitmap category by passing to the method, none of the default adjustment settings will apply to bitmaps. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel for the bitmap category by passing to the method, none of the default adjustment settings will apply to bitmaps. ## Examples - The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `ShowOutputChannels`, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `ShowOutputChannels`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet4"::: @@ -2375,17 +2375,17 @@ and methods to convert an image to a CMYK (cyan-magenta-yellow-black) color space and examine the intensities of one of the CMYK color channels. For example, suppose you write code that performs the following steps: + You can use the and methods to convert an image to a CMYK (cyan-magenta-yellow-black) color space and examine the intensities of one of the CMYK color channels. For example, suppose you write code that performs the following steps: 1. Create an . 2. Create an object. -3. Pass to the method of the object. +3. Pass to the method of the object. -4. Pass the path name of a color profile file to the method of the object. +4. Pass the path name of a color profile file to the method of the object. -5. Pass the paths of the and objects to the method. +5. Pass the paths of the and objects to the method. GDI+ will use the color-profile file to calculate the cyan component of each pixel in the image, and each pixel in the rendered image will be a shade of gray that indicates the intensity of its cyan channel. @@ -2438,17 +2438,17 @@ and methods to convert an image to a CMYK (cyan-magenta-yellow-black) color space and examine the intensities of one of the CMYK color channels. For example, suppose you write code that performs the following steps: + You can use the and methods to convert an image to a CMYK (cyan-magenta-yellow-black) color space and examine the intensities of one of the CMYK color channels. For example, suppose you write code that performs the following steps: 1. Create an . 2. Create an object. -3. Pass to the method of the object. +3. Pass to the method of the object. -4. Pass the path name of a color profile file to the method of the object. +4. Pass the path name of a color profile file to the method of the object. -5. Pass the paths of the and objects to the method. +5. Pass the paths of the and objects to the method. GDI+ will use the color-profile file to calculate the cyan component of each pixel in the image, and each pixel in the rendered image will be a shade of gray that indicates the intensity of its cyan channel. @@ -2456,7 +2456,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, the default settings apply to the bitmap category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel color-profile file for the bitmap category by passing to the method, none of the default adjustment settings will apply to bitmaps. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel color-profile file for the bitmap category by passing to the method, none of the default adjustment settings will apply to bitmaps. ]]> @@ -2788,12 +2788,12 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-remap table for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-remap table for the pen category by passing to the method, none of the default adjustment settings will apply to pens. ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2867,7 +2867,7 @@ 1. Opens an and draws it to the screen. -2. Creates an object and sets its threshold by using the method. +2. Creates an object and sets its threshold by using the method. 3. Draws the image to the screen by using the threshold of the object. @@ -2926,12 +2926,12 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the threshold for the pen category by passing to the method, none of the default adjustment settings will apply to pens. + As soon as you specify a color-adjustment or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the threshold for the pen category by passing to the method, none of the default adjustment settings will apply to pens. ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2985,7 +2985,7 @@ method is equivalent to calling and passing for the `color` parameter. specifies the color of pixels outside of a rendered image. This color is visible if the mode parameter is set to and the source rectangle passed to the method is larger than the image itself. + Calling the method is equivalent to calling and passing for the `color` parameter. specifies the color of pixels outside of a rendered image. This color is visible if the mode parameter is set to and the source rectangle passed to the method is larger than the image itself. @@ -3055,7 +3055,7 @@ method. + For a code example, see the method. ]]> @@ -3104,7 +3104,7 @@ method. + For a code example, see the method. ]]> diff --git a/xml/System.Drawing.Imaging/ImageCodecInfo.xml b/xml/System.Drawing.Imaging/ImageCodecInfo.xml index b090b715f72..0812792ff15 100644 --- a/xml/System.Drawing.Imaging/ImageCodecInfo.xml +++ b/xml/System.Drawing.Imaging/ImageCodecInfo.xml @@ -48,7 +48,7 @@ objects to various file formats. Image encoders are built into GDI+ for the BMP, JPEG, GIF, TIFF, and PNG formats. An encoder is invoked when you call the or method of a object. + GDI+ uses image encoders to convert the images stored in objects to various file formats. Image encoders are built into GDI+ for the BMP, JPEG, GIF, TIFF, and PNG formats. An encoder is invoked when you call the or method of a object. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -404,7 +404,7 @@ . + For an example, see . ]]> @@ -447,7 +447,7 @@ `e`, which is a parameter of the event handler. The code uses the method to retrieve all the codec information for all installed image encoders and codecs, and then draws all the information about each codec to the screen. + The following example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code uses the method to retrieve all the codec information for all installed image encoders and codecs, and then draws all the information about each codec to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Imaging.ClassicImageCodecExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Imaging/ImageCodecInfo/GetImageEncoders/form1.cs" id="Snippet1"::: diff --git a/xml/System.Drawing.Imaging/ImageFormat.xml b/xml/System.Drawing.Imaging/ImageFormat.xml index c3ed96e8ef8..92754364080 100644 --- a/xml/System.Drawing.Imaging/ImageFormat.xml +++ b/xml/System.Drawing.Imaging/ImageFormat.xml @@ -52,7 +52,7 @@ class indicate image formats such as bitmap (), enhanced metafile (), and icon (). For example, you can use the properties of the class to specify an image format when saving an image using the method. You can compare two image formats by using the method. + The properties of the class indicate image formats such as bitmap (), enhanced metafile (), and icon (). For example, you can use the properties of the class to specify an image format when saving an image using the method. You can compare two image formats by using the method. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -104,7 +104,7 @@ class to specify a particular format such as or , rather than constructing a new . + Typically you use the static properties of the class to specify a particular format such as or , rather than constructing a new . ]]> diff --git a/xml/System.Drawing.Imaging/ImageLockMode.xml b/xml/System.Drawing.Imaging/ImageLockMode.xml index d30bf799673..ef86e0870bf 100644 --- a/xml/System.Drawing.Imaging/ImageLockMode.xml +++ b/xml/System.Drawing.Imaging/ImageLockMode.xml @@ -34,15 +34,15 @@ Specifies flags that are passed to the flags parameter of the method. The method locks a portion of an image so that you can read or write the pixel data. - , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . - + , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Drawing.Imaging/Metafile.xml b/xml/System.Drawing.Imaging/Metafile.xml index e91b3d5e9de..e8cce084929 100644 --- a/xml/System.Drawing.Imaging/Metafile.xml +++ b/xml/System.Drawing.Imaging/Metafile.xml @@ -73,12 +73,12 @@ method to save a graphic image as a Windows Metafile Format (WMF) or Enhanced Metafile Format (EMF) file, the resulting file is saved as a Portable Network Graphics (PNG) file instead. This behavior occurs because the GDI+ component of the .NET Framework does not have an encoder that you can use to save files as .wmf or .emf files. + When you use the method to save a graphic image as a Windows Metafile Format (WMF) or Enhanced Metafile Format (EMF) file, the resulting file is saved as a Portable Network Graphics (PNG) file instead. This behavior occurs because the GDI+ component of the .NET Framework does not have an encoder that you can use to save files as .wmf or .emf files. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates how to create a and use the method. + The following code example demonstrates how to create a and use the method. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/EnumerateMetafile/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/EnumerateMetafile/Form1.vb" id="Snippet1"::: @@ -2188,7 +2188,7 @@ method. + The following code example demonstrates how to use the method. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/EnumerateMetafile/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/EnumerateMetafile/Form1.vb" id="Snippet1"::: diff --git a/xml/System.Drawing.Imaging/PropertyItem.xml b/xml/System.Drawing.Imaging/PropertyItem.xml index 3e761244c43..f5d94f50ffe 100644 --- a/xml/System.Drawing.Imaging/PropertyItem.xml +++ b/xml/System.Drawing.Imaging/PropertyItem.xml @@ -48,7 +48,7 @@ A is not intended to be used as a stand-alone object. A object is intended to be used by classes that are derived from . A object is used to retrieve and to change the metadata of existing image files, not to create the metadata. Therefore, the class does not have a defined `Public` constructor, and you cannot create an instance of a object. - To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . + To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . @@ -433,14 +433,14 @@ |Integer|Represented Type| |-------------|----------------------| -|1|Specifies that is an array of bytes.| -|2|Specifies that is a null-terminated ASCII string. If you set the type data member to ASCII type, you should set the property to the length of the string including the null terminator. For example, the string "Hello" would have a length of 6.| -|3|Specifies that is an array of unsigned short (16-bit) integers.| -|4|Specifies that is an array of unsigned long (32-bit) integers.| -|5|Specifies that data member is an array of pairs of unsigned long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| -|6|Specifies that is an array of bytes that can hold values of any data type.| -|7|Specifies that is an array of signed long (32-bit) integers.| -|10|Specifies that is an array of pairs of signed long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| +|1|Specifies that is an array of bytes.| +|2|Specifies that is a null-terminated ASCII string. If you set the type data member to ASCII type, you should set the property to the length of the string including the null terminator. For example, the string "Hello" would have a length of 6.| +|3|Specifies that is an array of unsigned short (16-bit) integers.| +|4|Specifies that is an array of unsigned long (32-bit) integers.| +|5|Specifies that data member is an array of pairs of unsigned long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| +|6|Specifies that is an array of bytes that can hold values of any data type.| +|7|Specifies that is an array of signed long (32-bit) integers.| +|10|Specifies that is an array of pairs of signed long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| For more information about property tags, see [Image Property Tag Constants](/windows/desktop/gdiplus/-gdiplus-constant-image-property-tag-constants). diff --git a/xml/System.Drawing.Printing/InvalidPrinterException.xml b/xml/System.Drawing.Printing/InvalidPrinterException.xml index 0053b65c963..155c6a42c72 100644 --- a/xml/System.Drawing.Printing/InvalidPrinterException.xml +++ b/xml/System.Drawing.Printing/InvalidPrinterException.xml @@ -50,13 +50,13 @@ Represents the exception that is thrown when you try to access a printer using printer settings that are not valid. - namespace overview. - + namespace overview. + ]]> @@ -146,11 +146,11 @@ The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -204,11 +204,11 @@ The that contains contextual information about the source or destination. Overridden. Sets the with information about the exception. - method sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. - + method sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. + ]]> diff --git a/xml/System.Drawing.Printing/Margins.xml b/xml/System.Drawing.Printing/Margins.xml index 14835504026..71e6bad61ed 100644 --- a/xml/System.Drawing.Printing/Margins.xml +++ b/xml/System.Drawing.Printing/Margins.xml @@ -58,26 +58,26 @@ Specifies the dimensions of the margins of a printed page. - class is used to manipulate the width of margins in and . is the type descriptor for this class. - - , , , and are properties that define the margins. creates an identical . determines if another object has the same dimensions as a . - - For more information about printing, see the namespace overview. - - - -## Examples - Use the , , and namespaces for this example. - - The following code example sets the default page settings for a document to margins of 1 inch on each side. - + class is used to manipulate the width of margins in and . is the type descriptor for this class. + + , , , and are properties that define the margins. creates an identical . determines if another object has the same dimensions as a . + + For more information about printing, see the namespace overview. + + + +## Examples + Use the , , and namespaces for this example. + + The following code example sets the default page settings for a document to margins of 1 inch on each side. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Overview/source.vb" id="Snippet1"::: + ]]> @@ -171,31 +171,31 @@ The bottom margin, in hundredths of an inch. Initializes a new instance of the class with the specified left, right, top, and bottom margins. - , , and namespaces for this example. - - The following code example sets the default page settings for a document to margins of 1 inch width on each side. - + , , and namespaces for this example. + + The following code example sets the default page settings for a document to margins of 1 inch width on each side. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Overview/source.vb" id="Snippet1"::: + ]]> - The parameter value is less than 0. - - -or- - - The parameter value is less than 0. - - -or- - - The parameter value is less than 0. - - -or- - + The parameter value is less than 0. + + -or- + + The parameter value is less than 0. + + -or- + + The parameter value is less than 0. + + -or- + The parameter value is less than 0. @@ -238,22 +238,22 @@ Gets or sets the bottom margin, in hundredths of an inch. The bottom margin, in hundredths of an inch. - member to 98. - - - -## Examples - Use the , , and namespaces for this example. - - The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. - + member to 98. + + + +## Examples + Use the , , and namespaces for this example. + + The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins.Left Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Bottom/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: + ]]> The property is set to a value that is less than 0. @@ -426,22 +426,22 @@ Gets or sets the left margin width, in hundredths of an inch. The left margin width, in hundredths of an inch. - member to 98. - - - -## Examples - Use the , , and namespaces for this example. - - The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. - + member to 98. + + + +## Examples + Use the , , and namespaces for this example. + + The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins.Left Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Bottom/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: + ]]> The property is set to a value that is less than 0. @@ -490,7 +490,7 @@ to indicate the , , , and properties of both margins have the same value; otherwise, . - ]]> + ]]> @@ -534,7 +534,7 @@ to indicate if the , , , or properties of both margins are not equal; otherwise, . - ]]> + ]]> @@ -577,22 +577,22 @@ Gets or sets the right margin width, in hundredths of an inch. The right margin width, in hundredths of an inch. - member to 98. - - - -## Examples - Use the , , and namespaces for this example. - - The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. - + member to 98. + + + +## Examples + Use the , , and namespaces for this example. + + The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins.Left Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Bottom/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: + ]]> The property is set to a value that is less than 0. @@ -640,22 +640,22 @@ Gets or sets the top margin width, in hundredths of an inch. The top margin width, in hundredths of an inch. - member to 98. - - - -## Examples - Use the , , and namespaces for this example. - - The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. - + member to 98. + + + +## Examples + Use the , , and namespaces for this example. + + The following code example sets the default page settings for a document to left and right margins of 1 inch in width, and top and bottom margins of 1.5 inches in width. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic Margins.Left Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/Margins/Bottom/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/Margins/Bottom/source.vb" id="Snippet1"::: + ]]> The property is set to a value that is less than 0. diff --git a/xml/System.Drawing.Printing/PageSettings.xml b/xml/System.Drawing.Printing/PageSettings.xml index 3e219c874a3..18b18d7d5b3 100644 --- a/xml/System.Drawing.Printing/PageSettings.xml +++ b/xml/System.Drawing.Printing/PageSettings.xml @@ -118,7 +118,7 @@ ## Remarks The parameterless constructor initializes all fields to their default values. - Typically, you do not create an instance of , but instead use the to set settings for all pages. + Typically, you do not create an instance of , but instead use the to set settings for all pages. ]]> @@ -160,7 +160,7 @@ constructor is similar to initializing a new instance of and setting the property. + The constructor is similar to initializing a new instance of and setting the property. ]]> @@ -345,9 +345,9 @@ method to copy relevant information to a `DEVMODE` structure from a . This method is useful when you want to make unmanaged Win32 calls that require a `DEVMODE`. + Call the method to copy relevant information to a `DEVMODE` structure from a . This method is useful when you want to make unmanaged Win32 calls that require a `DEVMODE`. - To copy information from a `DEVMODE` structure to the , call . + To copy information from a `DEVMODE` structure to the , call . ]]> @@ -616,14 +616,14 @@ ## Remarks A represents the size of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. - For information about how you can specify a custom paper size, see the constructor. + For information about how you can specify a custom paper size, see the constructor. ## Examples - The following code example sets three properties for the document's default page, including the paper size based upon the size selected in the `comboPaperSize` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. + The following code example sets three properties for the document's default page, including the paper size based upon the size selected in the `comboPaperSize` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -691,12 +691,12 @@ ## Remarks A represents the source of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. ## Examples - The following code example sets three properties for the document's default page, including the paper source based upon the source selected in the `comboPaperSource` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. + The following code example sets three properties for the document's default page, including the paper source based upon the source selected in the `comboPaperSource` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -807,12 +807,12 @@ ## Remarks A represents the printer resolution of through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. ## Examples - The following code example sets three properties for the document's default page, including the printer's resolution based upon the resolution selected in the `comboPrintResolution` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. + The following code example sets three properties for the document's default page, including the printer's resolution based upon the resolution selected in the `comboPrintResolution` combo box, and then prints the document using the method. The example requires that a variable named `printDoc` exists and that the specific combo boxes exist. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet4"::: @@ -917,7 +917,7 @@ ## Remarks Use this method to copy relevant information in a `DEVMODE` structure to the . - To copy information from the to a `DEVMODE`, call . + To copy information from the to a `DEVMODE`, call . ]]> diff --git a/xml/System.Drawing.Printing/PaperSize.xml b/xml/System.Drawing.Printing/PaperSize.xml index d5f6528ca63..ee9fc7d13c4 100644 --- a/xml/System.Drawing.Printing/PaperSize.xml +++ b/xml/System.Drawing.Printing/PaperSize.xml @@ -49,16 +49,16 @@ and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. + This class is used by the and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. - You can use the constructor to specify a custom paper size. The and property values can be set only for custom objects. + You can use the constructor to specify a custom paper size. The and property values can be set only for custom objects. For more information about printing, see the namespace overview. ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -88,8 +88,8 @@ |Property|Initial value| |--------------|-------------------| -||| -||| +||| +||| ]]> @@ -165,12 +165,12 @@ created with this constructor always has its property set to . The and property values can be set only for custom objects. + A created with this constructor always has its property set to . The and property values can be set only for custom objects. ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -222,7 +222,7 @@ and property values can be set only for custom objects. + This height measurement is for the portrait orientation of the paper. The and property values can be set only for custom objects. ]]> @@ -266,7 +266,7 @@ constructor to specify a custom paper size. + You can use the constructor to specify a custom paper size. ]]> @@ -321,7 +321,7 @@ ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -582,7 +582,7 @@ and property values can be set only for custom objects. + This width measurement is for the portrait orientation of the paper. The and property values can be set only for custom objects. ]]> diff --git a/xml/System.Drawing.Printing/PaperSource.xml b/xml/System.Drawing.Printing/PaperSource.xml index 3b735e2a000..f9850aab0a2 100644 --- a/xml/System.Drawing.Printing/PaperSource.xml +++ b/xml/System.Drawing.Printing/PaperSource.xml @@ -49,14 +49,14 @@ and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. + This class is used by and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. For more information about printing, see the namespace overview. ## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: @@ -106,8 +106,8 @@ |Property|Initial value| |--------------|-------------------| -||| -||| +||| +||| ]]> @@ -272,7 +272,7 @@ ## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: diff --git a/xml/System.Drawing.Printing/PreviewPrintController.xml b/xml/System.Drawing.Printing/PreviewPrintController.xml index 5d53588f7b7..cb08ab5bf8d 100644 --- a/xml/System.Drawing.Printing/PreviewPrintController.xml +++ b/xml/System.Drawing.Printing/PreviewPrintController.xml @@ -46,9 +46,9 @@ ## Remarks Typically, to use the print preview feature, you create an instance of a or class and set its property. The is used by the and classes, though you can use the when managing the display of your own print preview window. - When used with a or , sets the of the associated to a , performs the print preview, and sets the back to the original value. + When used with a or , sets the of the associated to a , performs the print preview, and sets the back to the original value. - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. For more information about printing, see the namespace overview. @@ -209,9 +209,9 @@ is called immediately after the raises the event. If an exception is thrown inside a event of a , this method is not called. + is called immediately after the raises the event. If an exception is thrown inside a event of a , this method is not called. - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. ]]> @@ -264,9 +264,9 @@ raises the event. Even if an uncaught exception was thrown during the print preview process, is called. + This method is called immediately after raises the event. Even if an uncaught exception was thrown during the print preview process, is called. - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. ]]> @@ -319,9 +319,9 @@ is called immediately before raises the event. + is called immediately before raises the event. - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. > [!NOTE] > Anti-aliasing, also known as gray scaling, makes the print preview look better. However, the use of anti-aliasing can slow down the rendering speed. For more information about anti-aliasing, see the property. @@ -375,11 +375,11 @@ is called immediately after raises the event. + is called immediately after raises the event. - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - verifies that the printer settings are valid. + verifies that the printer settings are valid. ]]> diff --git a/xml/System.Drawing.Printing/PrintAction.xml b/xml/System.Drawing.Printing/PrintAction.xml index 702cd7ccb06..a0f5a6ebb41 100644 --- a/xml/System.Drawing.Printing/PrintAction.xml +++ b/xml/System.Drawing.Printing/PrintAction.xml @@ -33,14 +33,14 @@ Specifies the type of print operation occurring. - is used by the type to indicate what type of event is occurring. - + is used by the type to indicate what type of event is occurring. + > [!NOTE] -> The does not reliably indicate the type of print operation occurring, and returns PrintToFile in all cases. - +> The does not reliably indicate the type of print operation occurring, and returns PrintToFile in all cases. + ]]> diff --git a/xml/System.Drawing.Printing/PrintController.xml b/xml/System.Drawing.Printing/PrintController.xml index ae801190360..b90db6a8898 100644 --- a/xml/System.Drawing.Printing/PrintController.xml +++ b/xml/System.Drawing.Printing/PrintController.xml @@ -47,7 +47,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] - When implemented in a derived class, controls how a is printed. invokes the print controller's , , , and methods, which in turn tell the printer how to print the document. Print preview uses a specialized . For an example of a print controller that is specialized for print preview, see the . + When implemented in a derived class, controls how a is printed. invokes the print controller's , , , and methods, which in turn tell the printer how to print the document. Print preview uses a specialized . For an example of a print controller that is specialized for print preview, see the . is used by , and not typically used directly. @@ -172,9 +172,9 @@ is called immediately after the raises the event. If an exception is thrown inside a event of a , is not called. + is called immediately after the raises the event. If an exception is thrown inside a event of a , is not called. - creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. (Use the method to set how to print a page in a document. For example, you can adjust page settings separately for each page.) The method clears the , while the method deallocates the object. + creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. (Use the method to set how to print a page in a document. For example, you can adjust page settings separately for each page.) The method clears the , while the method deallocates the object. ]]> @@ -227,9 +227,9 @@ is called immediately after the raises the event. + is called immediately after the raises the event. - creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. (Use the method to determine when and how to print a document. For example, you can delay printing for 30 minutes or adjust the printer settings for the document.) The method clears the , while the method deallocates the object. + creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. (Use the method to determine when and how to print a document. For example, you can delay printing for 30 minutes or adjust the printer settings for the document.) The method clears the , while the method deallocates the object. ]]> @@ -289,11 +289,11 @@ is called immediately before the raises the event. + is called immediately before the raises the event. - creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + creates the that is sent to the printer. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - Use the method to set how to print a page in a document. For example, you can adjust page settings separately for each page. + Use the method to set how to print a page in a document. For example, you can adjust page settings separately for each page. ]]> @@ -344,11 +344,11 @@ is called immediately after the raises the event. + is called immediately after the raises the event. - Use the method to determine when and how to print a document. For example, you can delay printing for 30 minutes or adjust the printer settings for the document. creates the that is sent to the printer. After is called, the method sets the to one of a single page. The method clears the , while the method deallocates the object. + Use the method to determine when and how to print a document. For example, you can delay printing for 30 minutes or adjust the printer settings for the document. creates the that is sent to the printer. After is called, the method sets the to one of a single page. The method clears the , while the method deallocates the object. - The method is a good place to verify that are valid. + The method is a good place to verify that are valid. ]]> diff --git a/xml/System.Drawing.Printing/PrintDocument.xml b/xml/System.Drawing.Printing/PrintDocument.xml index 2faa25e9be2..1f8d7506e2a 100644 --- a/xml/System.Drawing.Printing/PrintDocument.xml +++ b/xml/System.Drawing.Printing/PrintDocument.xml @@ -56,7 +56,7 @@ class, set properties such as the and , and call the method to start the printing process. Handle the event where you specify the output to print, by using the property of the . + Typically, you create an instance of the class, set properties such as the and , and call the method to start the printing process. Handle the event where you specify the output to print, by using the property of the . For more information about printing from a Windows Form application, see the [Windows Forms Print Support](/dotnet/framework/winforms/advanced/windows-forms-print-support). If you wish to print from a Windows Presentation Foundation application, see the namespace. @@ -113,7 +113,7 @@ , you set printer and page settings that affect the output through the and properties, respectively. + The parameterless constructor initializes all fields based upon the default printer. Typically, after creating a new , you set printer and page settings that affect the output through the and properties, respectively. @@ -228,7 +228,7 @@ ## Remarks You can specify several default page settings through the property. For example, the property specifies whether the page prints in color, the property specifies landscape or portrait orientation, and the property specifies the margins of the page. - To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. + To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. > [!NOTE] > After printing has started, changes to page settings through the property will not affect pages being printed. @@ -302,7 +302,7 @@ ## Examples - The following code example prints a document with the first page in color, if the printer supports it, and sets the to a user-friendly name. The example requires that a variable named `printDoc` has been created, and the and events are handled. + The following code example prints a document with the first page in color, if the printer supports it, and sets the to a user-friendly name. The example requires that a variable named `printDoc` has been created, and the and events are handled. Use the and namespaces for this example. @@ -409,9 +409,9 @@ method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). ]]> @@ -465,9 +465,9 @@ method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. The method is also called if the printing process is canceled or an exception occurs during the printing process. + The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. The method is also called if the printing process is canceled or an exception occurs during the printing process. - When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). ]]> @@ -521,9 +521,9 @@ method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). ]]> @@ -577,9 +577,9 @@ method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + When a derived class calls the method, it raises the event by invoking the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). ]]> @@ -641,9 +641,9 @@ object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. + Calculating the area available to print requires knowing the physical size of the paper, the margins for the page, and the location of the object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. - For example, if is `true`, and is set for 1 inch on each side, the object included in the is located 1 inch from the left and top of the page. If the printable area of the page is .25 of an inch on each side and is `false`, the object is located .25 of an inch from the left and top of the page. + For example, if is `true`, and is set for 1 inch on each side, the object included in the is located 1 inch from the left and top of the page. If the printable area of the page is .25 of an inch on each side and is `false`, the object is located .25 of an inch from the left and top of the page. > [!NOTE] > The printable area of a page varies from printer to printer and is not guaranteed to be symmetrical. @@ -692,10 +692,10 @@ Use the property to specify which printer should print the document. - The method prints the document without using a print dialog. Use a when you want to offer the user the ability to choose print settings. + The method prints the document without using a print dialog. Use a when you want to offer the user the ability to choose print settings. > [!NOTE] -> If an exception that is not handled by the method is thrown during printing, the printing of the document is aborted. +> If an exception that is not handled by the method is thrown during printing, the printing of the document is aborted. @@ -892,7 +892,7 @@ property of the . For example, to specify a line of text that should be printed, draw the text using the method. + To specify the output to print, use the property of the . For example, to specify a line of text that should be printed, draw the text using the method. In addition to specifying the output, you can indicate if there are additional pages to print by setting the property to `true`. The default is `false`, which indicates that there are no more pages to print. Individual page settings can also be modified through the and the print job can be canceled by setting the property to `true`. To print each page of a document using different page settings, handle the event. diff --git a/xml/System.Drawing.Printing/PrintEventArgs.xml b/xml/System.Drawing.Printing/PrintEventArgs.xml index 5d0fc787aa0..13aad57ce97 100644 --- a/xml/System.Drawing.Printing/PrintEventArgs.xml +++ b/xml/System.Drawing.Printing/PrintEventArgs.xml @@ -131,7 +131,7 @@ does not reliably indicate the type of print operation occurring, and returns in all cases. + The does not reliably indicate the type of print operation occurring, and returns in all cases. ]]> diff --git a/xml/System.Drawing.Printing/PrintPageEventArgs.xml b/xml/System.Drawing.Printing/PrintPageEventArgs.xml index 715eaa21a5b..690b13bc95f 100644 --- a/xml/System.Drawing.Printing/PrintPageEventArgs.xml +++ b/xml/System.Drawing.Printing/PrintPageEventArgs.xml @@ -52,7 +52,7 @@ For more information about printing with Windows Forms, see the namespace overview. If you wish to print from a Windows Presentation Foundation application, see the namespace. ## Examples - The following code example assumes a named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. + The following code example assumes a named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. Use the , , and namespaces for this example. @@ -217,7 +217,7 @@ named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. + The following code example assumes a named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. Use the , , and namespaces for this example. @@ -277,7 +277,7 @@ named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. + The following code example assumes a named `printButton` and a named `pd` have been created on a . Make sure the event for the is associated with the `printButton_Click` method and the event of the is associated with the `pd_PrintPage` method in the example. The `printButton_Click` method from the example calls the method raising the event, and prints the .bmp file specified in the `pd_PrintPage` method. To run this example, change the path to the bitmap you want to print. Use the , , and namespaces for this example. @@ -285,7 +285,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PrintPageEventArgs/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PrintPageEventArgs/Overview/source.vb" id="Snippet1"::: - For another example that shows how to use , see [How to: Print a Multi-Page Text File in Windows Forms](/dotnet/framework/winforms/advanced/how-to-print-a-multi-page-text-file-in-windows-forms). + For another example that shows how to use , see [How to: Print a Multi-Page Text File in Windows Forms](/dotnet/framework/winforms/advanced/how-to-print-a-multi-page-text-file-in-windows-forms). ]]> diff --git a/xml/System.Drawing.Printing/PrinterResolution.xml b/xml/System.Drawing.Printing/PrinterResolution.xml index 43cc236a9db..21d2756301a 100644 --- a/xml/System.Drawing.Printing/PrinterResolution.xml +++ b/xml/System.Drawing.Printing/PrinterResolution.xml @@ -45,9 +45,9 @@ and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. + This class is used by the and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. - Use the property to determine whether the printer resolution type is the value . If so, use the and properties to determine the printer resolution in the horizontal and vertical directions, respectively. + Use the property to determine whether the printer resolution type is the value . If so, use the and properties to determine the printer resolution in the horizontal and vertical directions, respectively. For more information on printing, see the namespace overview. @@ -103,7 +103,7 @@ |Property|Initial Value| |--------------|-------------------| -||| +||| ]]> @@ -242,7 +242,7 @@ property contains the value `DMRES_HIGH` if is set to , `DMRES_MEDIUM` if is set to , `DMRES_LOW` if is set to , and `DMRES_DRAFT` if is set to . + `dmPrintQuality` is a member of the `DEVMODE` (device mode) structure, which defines constants that map to printer quality settings. The property contains the value `DMRES_HIGH` if is set to , `DMRES_MEDIUM` if is set to , `DMRES_LOW` if is set to , and `DMRES_DRAFT` if is set to . For more information, see [DEVMODE structure](/windows/win32/api/wingdi/ns-wingdi-devmodea). diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml index 851ca63e0f8..356295bb320 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml @@ -53,14 +53,14 @@ ## Remarks The contains instances that represents the paper sizes through the property, which contains one of the values. - Typically, you set a page's paper size through the property to a valid instance available through the collection. + Typically, you set a page's paper size through the property to a valid instance available through the collection. - See the constructor to find out how you can specify a custom paper size. + See the constructor to find out how you can specify a custom paper size. ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -240,7 +240,7 @@ is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -287,7 +287,7 @@ or to throw an exception. + This method instantiates an enumerator that takes a snapshot of the current state of the collection. The enumerator does not have exclusive access to the collection, so multiple enumerators can have access to the same collection at the same time. Therefore, any changes made to the collection, either directly or through another enumerator, can cause or to throw an exception. Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. @@ -338,7 +338,7 @@ is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml index 555ff14c386..f289f117c51 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml @@ -53,12 +53,12 @@ ## Remarks The contains instances that represents the paper source trays through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid instance available through the collection. + Typically, you set a page's paper source through the property to a valid instance available through the collection. ## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: @@ -238,7 +238,7 @@ is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: @@ -285,7 +285,7 @@ or to throw an exception. + This method instantiates an enumerator that takes a snapshot of the current state of the collection. The enumerator does not have exclusive access to the collection, so multiple enumerators can have access to the same collection at the same time. Therefore, any changes made to the collection, either directly or through another enumerator, can cause or to throw an exception. Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. @@ -336,7 +336,7 @@ is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: diff --git a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml index 32fff7f3897..844425cb30a 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml @@ -53,9 +53,9 @@ ## Remarks The contains instances that represents the printer resolutions supported through the property, which contains one of the values. - Typically, you set the printer's resolution through the property to a valid instance available through the collection. + Typically, you set the printer's resolution through the property to a valid instance available through the collection. - If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. + If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. @@ -286,7 +286,7 @@ or to throw an exception. + This method instantiates an enumerator that takes a snapshot of the current state of the collection. The enumerator does not have exclusive access to the collection, so multiple enumerators can have access to the same collection at the same time. Therefore, any changes made to the collection, either directly or through another enumerator, can cause or to throw an exception. Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. diff --git a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml index a6f187362d1..c45c7ee81bd 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml @@ -271,7 +271,7 @@ or to throw an exception. + This method instantiates an enumerator that takes a snapshot of the current state of the collection. The enumerator does not have exclusive access to the collection, so multiple enumerators can have access to the same collection at the same time. Therefore, any changes made to the collection, either directly or through another enumerator, can cause or to throw an exception. Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. diff --git a/xml/System.Drawing.Printing/PrinterSettings.xml b/xml/System.Drawing.Printing/PrinterSettings.xml index f1bf954e12f..b337cb8a7f7 100644 --- a/xml/System.Drawing.Printing/PrinterSettings.xml +++ b/xml/System.Drawing.Printing/PrinterSettings.xml @@ -57,7 +57,7 @@ through or properties to modify printer settings. The most common printer setting is , which specifies the printer to print to. + Typically, you access a through or properties to modify printer settings. The most common printer setting is , which specifies the printer to print to. For more information about printing with Windows Forms, see the namespace overview. If you wish to print from a Windows Presentation Foundation application, see the namespace. @@ -119,7 +119,7 @@ ## Remarks The parameterless constructor initializes all fields to their default values. - Typically, you do not create an instance of , but instead use the to set settings for the printer. + Typically, you do not create an instance of , but instead use the to set settings for the printer. ]]> @@ -162,7 +162,7 @@ to one of the values. + To print using duplex, and if the printer supports it, set to one of the values. ]]> @@ -251,7 +251,7 @@ ## Remarks Collating is performed only when the number of copies is greater than 1. Set the property to specify the number of copies to print. - Setting to `true` will print a complete copy of the document before the first page of the next copy is printed. `false` will print each page by the number of copies specified before printing the next page. + Setting to `true` will print a complete copy of the document before the first page of the next copy is printed. `false` will print each page by the number of copies specified before printing the next page. ]]> @@ -364,7 +364,7 @@ method, you can obtain a for the printer without creating a print job. You can use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. + With the method, you can obtain a for the printer without creating a print job. You can use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. ]]> @@ -413,7 +413,7 @@ method, you can obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. + With the method, you can obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. ]]> @@ -458,7 +458,7 @@ method, you can obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. + With the method, you can obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. ]]> @@ -506,7 +506,7 @@ method allows you to obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. + The method allows you to obtain a for the printer without creating a print job. Use the to make decisions on how to layout visual elements like fonts, sizes, and type styles of a complex print job. ]]> @@ -655,11 +655,11 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> @@ -716,7 +716,7 @@ to a for a different printer is not supported. When you are done with the handle that is created through this method, you must deallocate it yourself by calling the native Win32 `GlobalFree` method. When you call this method, you pass as a parameter the return value from the method. + `DEVMODE` structures are device specific. Copying a `DEVMODE` structure from one to a for a different printer is not supported. When you are done with the handle that is created through this method, you must deallocate it yourself by calling the native Win32 `GlobalFree` method. When you call this method, you pass as a parameter the return value from the method. ]]> @@ -766,7 +766,7 @@ ## Remarks `DEVMODE` structures are device specific. Copying a `DEVMODE` structure from one to a for a different printer is not supported. - When you are done with the handle that is created through this method, you must deallocate it yourself by calling the native Win32 `GlobalFree` method. When you call this method, you pass as a parameter the return value from the method. + When you are done with the handle that is created through this method, you must deallocate it yourself by calling the native Win32 `GlobalFree` method. When you call this method, you pass as a parameter the return value from the method. ]]> @@ -811,7 +811,7 @@ method. + When you are done with the handle that is created through this method, you must deallocate it yourself by calling the native Win32 `GlobalFree` method. When you call this method, you pass as a parameter the return value from the method. ]]> @@ -907,7 +907,7 @@ always returns `false` when you explicitly set the property to a string value other than `null`. + always returns `false` when you explicitly set the property to a string value other than `null`. @@ -1090,12 +1090,12 @@ property after setting the to safely determine if the printer is valid. + When you get or set some properties, a valid printer is required or else an exception is raised. To avoid exceptions, use the property after setting the to safely determine if the printer is valid. ## Examples - The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: + The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -1243,7 +1243,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -1296,7 +1296,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -1345,14 +1345,14 @@ ## Remarks The contains instances that represent the paper sizes through the property, which contains one of the values. - Typically, you set a page's paper size through the property to a valid available through the collection. + Typically, you set a page's paper size through the property to a valid available through the collection. - To specify a custom paper size, see the constructor. + To specify a custom paper size, see the constructor. ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -1406,12 +1406,12 @@ ## Remarks The contains instances that represent the paper source trays through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. ## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: @@ -1463,14 +1463,14 @@ to determine if the printer name is recognized as a valid printer on the system. + After setting the printer name, call to determine if the printer name is recognized as a valid printer on the system. You can also use the property to get a list of printers installed on the system. ## Examples - The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: + The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -1530,9 +1530,9 @@ ## Remarks The contains instances that represent the printer resolutions supported through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. - If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. + If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. @@ -1628,11 +1628,11 @@ property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. + The property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> @@ -1691,7 +1691,7 @@ property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. + The property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. > [!NOTE] > The property is only used by the and cannot be set programmatically. The `Print to file` option only appears on the when the property is set to `true`. @@ -1823,7 +1823,7 @@ to `true`. + To print using color, and if the printer supports it, set to `true`. @@ -1883,11 +1883,11 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> diff --git a/xml/System.Drawing.Printing/PrintingPermission.xml b/xml/System.Drawing.Printing/PrintingPermission.xml index 3e770e90865..117e0b02bdc 100644 --- a/xml/System.Drawing.Printing/PrintingPermission.xml +++ b/xml/System.Drawing.Printing/PrintingPermission.xml @@ -137,11 +137,11 @@ One of the values. Initializes a new instance of the class with either fully restricted or unrestricted access, as specified. - @@ -182,11 +182,11 @@ Creates and returns an identical copy of the current permission object. A copy of the current permission object. - @@ -273,11 +273,11 @@ Creates and returns a permission that is the intersection of the current permission object and a target permission object. A new permission object that represents the intersection of the current object and the specified target. This object is if the intersection is empty. - @@ -365,11 +365,11 @@ if permission is unrestricted; otherwise, . - @@ -489,11 +489,11 @@ Creates a permission that combines the permission object and the target permission object. A new permission object that represents the union of the current permission object and the specified permission object. - is a permission that represents all the operations represented by the current permission object, and all the operations represented by the specified permission object. - + is a permission that represents all the operations represented by the current permission object, and all the operations represented by the specified permission object. + ]]> diff --git a/xml/System.Drawing.Printing/StandardPrintController.xml b/xml/System.Drawing.Printing/StandardPrintController.xml index 120b4fcb579..fe11e74887b 100644 --- a/xml/System.Drawing.Printing/StandardPrintController.xml +++ b/xml/System.Drawing.Printing/StandardPrintController.xml @@ -41,13 +41,13 @@ Specifies a print controller that sends information to a printer. - uses this class. - - For more information on printing, see the namespace overview. - + uses this class. + + For more information on printing, see the namespace overview. + ]]> @@ -128,15 +128,15 @@ A that contains data about how to print a page in the document. Completes the control sequence that determines when and how to print a page of a document. - is called immediately after the raises the event. If an exception is thrown inside a event of a , is not called. - - creates the object that is sent to the printer. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. - - When is called from a printing context of a a of is required. Printing to the default printer requires a of . All other calls this method requires a of - + is called immediately after the raises the event. If an exception is thrown inside a event of a , is not called. + + creates the object that is sent to the printer. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. + + When is called from a printing context of a a of is required. Printing to the default printer requires a of . All other calls this method requires a of + ]]> The native Win32 Application Programming Interface (API) could not finish writing to a page. @@ -186,19 +186,19 @@ A that contains data about how to print the document. Completes the control sequence that determines when and how to print a document. - is called immediately after raises the event. Even if an uncaught exception was thrown during the printing process, is called. - - creates the object that is sent to the printer. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. - + is called immediately after raises the event. Even if an uncaught exception was thrown during the printing process, is called. + + creates the object that is sent to the printer. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. + ]]> - The native Win32 Application Programming Interface (API) could not complete the print job. - - -or- - + The native Win32 Application Programming Interface (API) could not complete the print job. + + -or- + The native Windows API could not delete the specified device context (DC). @@ -246,19 +246,19 @@ Begins the control sequence that determines when and how to print a page in a document. A object that represents a page from a . - is called immediately before raises the event. - - creates the object used in printing. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. - + is called immediately before raises the event. + + creates the object used in printing. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. + ]]> - The native Win32 Application Programming Interface (API) could not prepare the printer driver to accept data. - - -or- - + The native Win32 Application Programming Interface (API) could not prepare the printer driver to accept data. + + -or- + The native Windows API could not update the specified printer or plotter device context (DC) using the specified information. @@ -304,15 +304,15 @@ A that contains data about how to print the document. Begins the control sequence that determines when and how to print a document. - is called immediately after raises the event. - - creates the object used in printing. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. - - verifies that the printer settings are valid. - + is called immediately after raises the event. + + creates the object used in printing. After is called, the method sets the object to a graphic of a single page. The method clears the object, while the method deallocates the object. + + verifies that the printer settings are valid. + ]]> The printer settings are not valid. diff --git a/xml/System.Drawing.Text/FontCollection.xml b/xml/System.Drawing.Text/FontCollection.xml index 1398f8314fc..3b948f64061 100644 --- a/xml/System.Drawing.Text/FontCollection.xml +++ b/xml/System.Drawing.Text/FontCollection.xml @@ -100,10 +100,10 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Drawing.Text/PrivateFontCollection.xml b/xml/System.Drawing.Text/PrivateFontCollection.xml index bea130d57cf..4a321a06738 100644 --- a/xml/System.Drawing.Text/PrivateFontCollection.xml +++ b/xml/System.Drawing.Text/PrivateFontCollection.xml @@ -127,7 +127,7 @@ is not supported on operating systems before Windows 2000. When using a private font on operating systems before Windows 2000, the default font, typically Microsoft Sans Serif, will be substituted. + Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If you try to use a font that is not supported, such as an unsupported OpenType font or a Bitmap font, an exception will occur. The is not supported on operating systems before Windows 2000. When using a private font on operating systems before Windows 2000, the default font, typically Microsoft Sans Serif, will be substituted. ]]> @@ -176,7 +176,7 @@ method, passing `true`, to set GDI+ rendering on the application, or on individual controls by setting the control's property to `true`. Some controls cannot be rendered with GDI+. + To use the memory font, text on a control must be rendered with GDI+. Use the method, passing `true`, to set GDI+ rendering on the application, or on individual controls by setting the control's property to `true`. Some controls cannot be rendered with GDI+. ]]> diff --git a/xml/System.Drawing.Text/TextRenderingHint.xml b/xml/System.Drawing.Text/TextRenderingHint.xml index 7a136d4ba28..da820ae931d 100644 --- a/xml/System.Drawing.Text/TextRenderingHint.xml +++ b/xml/System.Drawing.Text/TextRenderingHint.xml @@ -34,22 +34,22 @@ Specifies the quality of text rendering. - and properties and the enumeration. - - This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangeTextRenderingHintAndTextContrast` method when handling the form's event, passing `e` as . - + and properties and the enumeration. + + This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangeTextRenderingHintAndTextContrast` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.GraphicsProperties/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Clip/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/Clip/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/Clip/form1.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Drawing/Bitmap.xml b/xml/System.Drawing/Bitmap.xml index 5227e9d89c0..6aed6005c56 100644 --- a/xml/System.Drawing/Bitmap.xml +++ b/xml/System.Drawing/Bitmap.xml @@ -75,17 +75,17 @@ ## Remarks A bitmap consists of the pixel data for a graphics image and its attributes. There are many standard formats for saving a bitmap to a file. GDI+ supports the following file formats: BMP, GIF, EXIF, JPG, PNG, and TIFF. For more information about supported formats, see [Types of Bitmaps](/dotnet/desktop/winforms/advanced/types-of-bitmaps). - You can create images from files, streams, and other sources by using one of the constructors and save them to a stream or to the file system with the method. Images are drawn to the screen or to memory by using the method of the object. For a list of topics about working with image files, see [Working with Images, Bitmaps, Icons, and Metafiles](/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). + You can create images from files, streams, and other sources by using one of the constructors and save them to a stream or to the file system with the method. Images are drawn to the screen or to memory by using the method of the object. For a list of topics about working with image files, see [Working with Images, Bitmaps, Icons, and Metafiles](/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] > [!NOTE] -> The class is not accessible across application domains. For example, if you create a dynamic and create several brushes, pens, and bitmaps in that domain, then pass these objects back to the main application domain, you can successfully use the pens and brushes. However, if you call the method to draw the marshaled , you receive the following exception: +> The class is not accessible across application domains. For example, if you create a dynamic and create several brushes, pens, and bitmaps in that domain, then pass these objects back to the main application domain, you can successfully use the pens and brushes. However, if you call the method to draw the marshaled , you receive the following exception: > > **Remoting cannot find field "native image" on type "System.Drawing.Image".** ## Examples - The following code example demonstrates how to construct a new from a file, using the and methods to recolor the image. It also uses the , , and properties. + The following code example demonstrates how to construct a new from a file, using the and methods to recolor the image. It also uses the , , and properties. This example is designed to be used with a Windows Forms that contains a , , and named `Label1`, `PictureBox1`, and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. @@ -437,7 +437,7 @@ ## Examples - The following code example demonstrates how to construct a new bitmap from a file. The example uses the and methods to recolor the image. It also uses the property. + The following code example demonstrates how to construct a new bitmap from a file. The example uses the and methods to recolor the image. It also uses the property. This example is designed to be used with a Windows Form that contains a , and named `Label1`, `PictureBox1` and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. @@ -493,7 +493,7 @@ ## Examples - The following code example demonstrates how to construct a bitmap from a type, and how to use the method. To run this example, paste the code into a Windows Form. Handle the form's event and call the `ConstructFromResourceSaveAsGif` method, passing `e` as + The following code example demonstrates how to construct a bitmap from a type, and how to use the method. To run this example, paste the code into a Windows Form. Handle the form's event and call the `ConstructFromResourceSaveAsGif` method, passing `e` as :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BmpCtorAndSave/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form11.cs" id="Snippet1"::: @@ -584,7 +584,7 @@ that this method creates takes its horizontal and vertical resolution from the and properties of `g`, respectively. + The new that this method creates takes its horizontal and vertical resolution from the and properties of `g`, respectively. ]]> @@ -681,7 +681,7 @@ ## Examples - The following code example shows how to use the constructor. This example is designed to be used with Windows Forms and requires a parameter, which is a parameter of the event. + The following code example shows how to use the constructor. This example is designed to be used with Windows Forms and requires a parameter, which is a parameter of the event. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippetconstructor"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippetconstructor"::: @@ -1048,7 +1048,7 @@ requires security permission to call unmanaged code. For a managed alternative for creating a bitmap from an embedded resource, see . works only with bitmaps that are named resources in a DLL. + requires security permission to call unmanaged code. For a managed alternative for creating a bitmap from an embedded resource, see . works only with bitmaps that are named resources in a DLL. ]]> @@ -1111,7 +1111,7 @@ ## Examples - The following code example demonstrates how to use the method. + The following code example demonstrates how to use the method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicBitmapExamples/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Clone/form1.cs" id="Snippet4"::: @@ -1174,7 +1174,7 @@ ## Examples - The following code example demonstrates how to use the .method. + The following code example demonstrates how to use the .method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicBitmapExamples/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Clone/form1.cs" id="Snippet5"::: @@ -1242,7 +1242,7 @@ - Gets an icon handle for the . -- Sets the attribute of the form to an icon created from the handle. +- Sets the attribute of the form to an icon created from the handle. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicBitmapExamples/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Clone/form1.cs" id="Snippet6"::: @@ -1365,7 +1365,7 @@ method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the method, although the method offers better performance for large-scale changes. + Use the method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the method, although the method offers better performance for large-scale changes. The specifies the attributes of the , such as size, pixel format, the starting address of the pixel data in memory, and length of each scan line (stride). @@ -1374,7 +1374,7 @@ ## Examples - The following code example demonstrates how to use the , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. This example is not designed to work correctly with all pixel formats, but to provide an example of how to use the method. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . + The following code example demonstrates how to use the , , , and properties; the and methods; and the enumeration. This example is designed to be used with Windows Forms. This example is not designed to work correctly with all pixel formats, but to provide an example of how to use the method. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet5"::: @@ -1435,11 +1435,11 @@ method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the method, although the method offers better performance for large-scale changes. + Use the method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the method, although the method offers better performance for large-scale changes. When calling this method, you should use a member of the enumeration that contains a specific bits-per-pixel (BPP) value. Using values, such as and , will throw an . Also, passing the incorrect pixel format for a bitmap will throw an . - This version of the method is intended to be used with a `flags` value of . + This version of the method is intended to be used with a `flags` value of . ]]> @@ -1497,9 +1497,9 @@ . If no transparent color is specified by the system, is the transparent color. + The system palette defines one color as the default transparent, or alpha, color. This method makes the default transparent color transparent for this . If no transparent color is specified by the system, is the transparent color. - When you call , the bitmap will be converted to the format, as this format supports an alpha channel. + When you call , the bitmap will be converted to the format, as this format supports an alpha channel. @@ -1555,7 +1555,7 @@ , the bitmap will be converted to the format, as this format supports an alpha channel. + When you call , the bitmap will be converted to the format, as this format supports an alpha channel. @@ -1621,7 +1621,7 @@ method to set the color of an individual pixel in an image programmatically. You can also change an image programmatically by using the method. Typically for large-scale changes, the method offers better performance. + Use method to set the color of an individual pixel in an image programmatically. You can also change an image programmatically by using the method. Typically for large-scale changes, the method offers better performance. @@ -1689,7 +1689,7 @@ ## Examples - The following example code shows how to use the method. + The following example code shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippetsetresolution"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippetsetresolution"::: @@ -1743,7 +1743,7 @@ ## Examples - The following code example demonstrates how to use the , , , and properties; the and methods; and the enumeration. This example is not designed to work correctly with all pixel formats, but to provide an example of how to use the method. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . + The following code example demonstrates how to use the , , , and properties; the and methods; and the enumeration. This example is not designed to work correctly with all pixel formats, but to provide an example of how to use the method. This example is designed to be used with Windows Forms. To run this example, paste it into a form and handle the form's event by calling the `LockUnlockBitsExample` method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet5"::: diff --git a/xml/System.Drawing/Brush.xml b/xml/System.Drawing/Brush.xml index 3abc730e3ae..07cb71b1b86 100644 --- a/xml/System.Drawing/Brush.xml +++ b/xml/System.Drawing/Brush.xml @@ -179,12 +179,12 @@ allows the resources used by this object to be reallocated for other purposes. + Calling allows the resources used by this object to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Drawing/BufferedGraphics.xml b/xml/System.Drawing/BufferedGraphics.xml index 6d75a7c05c3..62a6bfe9781 100644 --- a/xml/System.Drawing/BufferedGraphics.xml +++ b/xml/System.Drawing/BufferedGraphics.xml @@ -54,24 +54,24 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] > [!NOTE] -> The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. +> The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. - The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. + The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. The property can be used for drawing to the graphics buffer. This property provides access to the object that draws to the graphics buffer allocated for this object. - The method with no arguments draws the contents of the graphics buffer to the surface specified when the buffer was allocated. Other overloads of the method allow you to specify a object or an object that points to a device context to which to draw the contents of the graphics buffer. + The method with no arguments draws the contents of the graphics buffer to the surface specified when the buffer was allocated. Other overloads of the method allow you to specify a object or an object that points to a device context to which to draw the contents of the graphics buffer. For more information about drawing double-buffered graphics, see [Double Buffered Graphics](/dotnet/framework/winforms/advanced/double-buffered-graphics). ## Examples The following code example demonstrates using a object to draw graphics using several types of buffering implementations. Clicking the form alternately starts and stops a timer that causes draw updates. The draw updates allow you to observe the effect of double buffering. Right-clicking the form cycles through the following drawing modes: -- Drawing directly to the for a . +- Drawing directly to the for a . -- Drawing by overriding the method using the control style. +- Drawing by overriding the method using the control style. -- Drawing by overriding the method for the form method without using the control style. +- Drawing by overriding the method for the form method without using the control style. In each mode, text is drawn that identifies the current mode and describes the behavior that occurs when each mouse button is pressed. @@ -129,10 +129,10 @@ when you are finished using the object. The method leaves the object in an unusable state. After calling , you must release all references to the object so the garbage collector can reclaim the memory that the object was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the object. The method leaves the object in an unusable state. After calling , you must release all references to the object so the garbage collector can reclaim the memory that the object was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the object. Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the object. Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -262,7 +262,7 @@ method of the used to create this object. + This method writes the contents of the graphics buffer to the device specified by calling the method of the used to create this object. ]]> diff --git a/xml/System.Drawing/BufferedGraphicsContext.xml b/xml/System.Drawing/BufferedGraphicsContext.xml index ec1d0c17be2..8e918fb01f2 100644 --- a/xml/System.Drawing/BufferedGraphicsContext.xml +++ b/xml/System.Drawing/BufferedGraphicsContext.xml @@ -52,9 +52,9 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] > [!NOTE] -> The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the control styles flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. +> The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the control styles flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. - The class provides methods for creating and configuring a graphics buffer. The method creates a , which is a wrapper for a graphics buffer that also provides methods you can use to write to the buffer and render its contents to an output device. + The class provides methods for creating and configuring a graphics buffer. The method creates a , which is a wrapper for a graphics buffer that also provides methods you can use to write to the buffer and render its contents to an output device. You can retrieve the for the current application domain from the static property. For graphically intensive applications such as animation, you can create a dedicated using the constructor, but for most applications the property will be sufficient. @@ -109,7 +109,7 @@ For graphically intensive applications such as animation, you can sometimes improve performance by using a dedicated instead of the default instance provided by the . This allows you to create and manage graphics buffers individually. > [!NOTE] -> You should always call when you finish using a dedicated . +> You should always call when you finish using a dedicated . For more information about dedicated graphics buffers, see [How to: Manually Manage Buffered Graphics](/dotnet/framework/winforms/advanced/how-to-manually-manage-buffered-graphics). @@ -169,12 +169,12 @@ method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. + When you call the method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. ## Examples - The following code example demonstrates creating a graphics buffer using the method. This code is part of a larger example provided for the class. + The following code example demonstrates creating a graphics buffer using the method. This code is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/BufferingExamples/CPP/bufferingexamples.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/BufferedGraphics/Render/bufferingexamples.cs" id="Snippet3"::: @@ -229,12 +229,12 @@ method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. + When you call the method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. ## Examples - The following code example demonstrates creating a graphics buffer using the method. This code is part of a larger example provided for the class. + The following code example demonstrates creating a graphics buffer using the method. This code is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/BufferingExamples/CPP/bufferingexamples.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/BufferedGraphics/Render/bufferingexamples.cs" id="Snippet4"::: @@ -286,10 +286,10 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the method of the . +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the method of the . ]]> @@ -413,7 +413,7 @@ size will be used temporarily and then discarded when the object is released. + This property allows you to get or set the maximum dimensions for a buffer that should be retained in memory. You can allocate a buffer of any size, however any buffer with dimensions greater than the size will be used temporarily and then discarded when the object is released. diff --git a/xml/System.Drawing/BufferedGraphicsManager.xml b/xml/System.Drawing/BufferedGraphicsManager.xml index ea3a768ae7c..1d869382c66 100644 --- a/xml/System.Drawing/BufferedGraphicsManager.xml +++ b/xml/System.Drawing/BufferedGraphicsManager.xml @@ -50,9 +50,9 @@ ## Remarks The class allows you to implement custom double buffering for your graphics. Graphics that use double buffering can reduce or eliminate flicker that is caused by redrawing a display surface. - This class has one static property, , which returns the main for the current application domain. The class creates instances that can be used to draw buffered graphics. + This class has one static property, , which returns the main for the current application domain. The class creates instances that can be used to draw buffered graphics. - The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. + The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. For more information on double buffering, see [Double Buffered Graphics](/dotnet/framework/winforms/advanced/double-buffered-graphics), , and . diff --git a/xml/System.Drawing/CharacterRange.xml b/xml/System.Drawing/CharacterRange.xml index 6089fcc60ae..0afd108b4b6 100644 --- a/xml/System.Drawing/CharacterRange.xml +++ b/xml/System.Drawing/CharacterRange.xml @@ -43,15 +43,15 @@ Specifies a range of character positions within a string. - and use it to highlight part of a string. This example is designed to be used with Windows Forms. Paste the example into a form and call the `HighlightACharacterRange` method when handling the form's event, passing `e` as . - + and use it to highlight part of a string. This example is designed to be used with Windows Forms. Paste the example into a form and call the `HighlightACharacterRange` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -97,15 +97,15 @@ The number of positions in the range. Initializes a new instance of the structure, specifying a range of character positions within a string. - and use it to highlight part of a string. This example is designed to be used with Windows Forms. Paste the example into a form and call the `HighlightACharacterRange` method when handling the form's event, passing `e` as . - + and use it to highlight part of a string. This example is designed to be used with Windows Forms. Paste the example into a form and call the `HighlightACharacterRange` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -205,19 +205,19 @@ to indicate the specified object is an instance with the same and value as this instance; otherwise, . - to test for equality. - - - -## Examples - The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeEquality2` method from the event-handling method, passing `e` as . - + to test for equality. + + + +## Examples + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeEquality2` method from the event-handling method, passing `e` as . + :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet2"::: + ]]> @@ -402,19 +402,19 @@ to indicate the two objects have the same and values; otherwise, . - method. - - The equivalent method for this operator is - -## Examples - The following example demonstrates how to use the operator. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeEquality1` method from the event-handling method, passing `e` as . - + method. + + The equivalent method for this operator is + +## Examples + The following example demonstrates how to use the operator. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeEquality1` method from the event-handling method, passing `e` as . + :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet1"::: + ]]> @@ -458,19 +458,19 @@ to indicate the either the or values of the two objects differ; otherwise, . - method returns the opposite of the method. - - The equivalent method for this operator is - -## Examples - The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeInequality` method from the event-handling method, passing `e` as . - + method returns the opposite of the method. + + The equivalent method for this operator is + +## Examples + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CharacterRangeInequality` method from the event-handling method, passing `e` as . + :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Drawing/Color.xml b/xml/System.Drawing/Color.xml index bd98dffd191..dd3cdf66028 100644 --- a/xml/System.Drawing/Color.xml +++ b/xml/System.Drawing/Color.xml @@ -116,13 +116,13 @@ Named colors are represented by using the properties of the structure. -The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. The alpha component specifies the transparency of the color: 0 is fully transparent, and 255 is fully opaque. To determine the alpha, red, green, or blue component of a color, use the , , , or property, respectively. You can create a custom color by using one of the methods. +The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. The alpha component specifies the transparency of the color: 0 is fully transparent, and 255 is fully opaque. To determine the alpha, red, green, or blue component of a color, use the , , , or property, respectively. You can create a custom color by using one of the methods. For more information about these colors, see [List of colors by name](/uwp/api/windows.ui.colors#remarks). ## Examples -The following code example demonstrates the , , , and properties of a , and the member. +The following code example demonstrates the , , , and properties of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -186,12 +186,12 @@ This example is designed to be used with a Windows Form. Paste the code into the value of 255 represents an opaque color. An value from 1 through 254 represents a semitransparent color. The color becomes more opaque as approaches 255. + The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). The alpha component specifies the transparency of the color: 0 is fully transparent, and 255 is fully opaque. Likewise, an value of 255 represents an opaque color. An value from 1 through 254 represents a semitransparent color. The color becomes more opaque as approaches 255. ## Examples - The following code example demonstrates the , , , and properties of a , and the member. + The following code example demonstrates the , , , and properties of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -474,12 +474,12 @@ This example is designed to be used with a Windows Form. Paste the code into the is a value from 0 to 255 with 0 representing no blue and 255 representing fully blue. + The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. Likewise, is a value from 0 to 255 with 0 representing no blue and 255 representing fully blue. ## Examples - The following code example demonstrates the , , , and properties of a , and the member. + The following code example demonstrates the , , , and properties of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -2265,7 +2265,7 @@ This example is designed to be used with a Windows Form. Paste the code into the structures. To compare colors based solely on their ARGB values, you should use the method. This is because the and members determine equivalency using more than just the ARGB value of the colors. For example, and `FromArgb(0,0,0)` are not considered equal, since is a named color and `FromArgb(0,0,0)` is not. + This structure only does comparisons with other structures. To compare colors based solely on their ARGB values, you should use the method. This is because the and members determine equivalency using more than just the ARGB value of the colors. For example, and `FromArgb(0,0,0)` are not considered equal, since is a named color and `FromArgb(0,0,0)` is not. ]]> @@ -2847,12 +2847,12 @@ This example is designed to be used with a Windows Form. Paste the code into the enumeration. If the `name` parameter is not the valid name of a predefined color, the method creates a structure that has an ARGB value of 0 (that is, all ARGB components are 0). + A predefined color is also called a known color and is represented by an element of the enumeration. If the `name` parameter is not the valid name of a predefined color, the method creates a structure that has an ARGB value of 0 (that is, all ARGB components are 0). ## Examples - The following code example demonstrates the , , , , and members of a , and the member. + The following code example demonstrates the , , , , and members of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -2959,12 +2959,12 @@ This example is designed to be used with a Windows Form. Paste the code into the is a value from 0 to 255 with 0 representing no green and 255 representing fully green. + The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. Likewise, is a value from 0 to 255 with 0 representing no green and 255 representing fully green. ## Examples - The following code example demonstrates the , , , and properties of a , and the member. + The following code example demonstrates the , , , and properties of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -3798,7 +3798,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. ]]> @@ -3850,7 +3850,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. ]]> @@ -3901,7 +3901,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a system color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a system color. ]]> @@ -5867,12 +5867,12 @@ This example is designed to be used with a Windows Form. Paste the code into the structures. It also does a comparison of some state flags. If you want to compare just the ARGB values of two structures, compare them using the method. + This method compares more than the ARGB values of the structures. It also does a comparison of some state flags. If you want to compare just the ARGB values of two structures, compare them using the method. ## Examples - The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's event. + The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet2"::: @@ -5940,12 +5940,12 @@ This example is designed to be used with a Windows Form. Paste the code into the structures. It also does a comparison of some state flags. If you want to compare just the ARGB values of two structures, use the method. + This method compares more than the ARGB values of the structures. It also does a comparison of some state flags. If you want to compare just the ARGB values of two structures, use the method. ## Examples - The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. + The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet3"::: @@ -6624,12 +6624,12 @@ This example is designed to be used with a Windows Form. Paste the code into the ## Remarks The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. Likewise, - is a value from 0 to 255 with 0 representing no red and 255 representing fully red. + is a value from 0 to 255 with 0 representing no red and 255 representing fully red. ## Examples - The following code example demonstrates the , , , and properties of a , and the member. + The following code example demonstrates the , , , and properties of a , and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -7576,7 +7576,7 @@ This example is designed to be used with a Windows Form. Paste the code into the Each of the rectangles is painted a that matches the criteria stated in the first bullet. The name of the and its component values are also displayed. - This example displays certain known colors, the names of the colors, and their four component values. The method is used as a preliminary step to display the component values. + This example displays certain known colors, the names of the colors, and their four component values. The method is used as a preliminary step to display the component values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicColorExamples/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/FromArgb/form1.cs" id="Snippet9"::: @@ -7631,7 +7631,7 @@ This example is designed to be used with a Windows Form. Paste the code into the enumeration. When the method is applied to a structure that is created by using the method, returns 0, even if the ARGB value matches the ARGB value of a predefined color. also returns 0 when it is applied to a structure that is created by using the method with a string name that is not valid. + A predefined color is also called a known color and is represented by an element of the enumeration. When the method is applied to a structure that is created by using the method, returns 0, even if the ARGB value matches the ARGB value of a predefined color. also returns 0 when it is applied to a structure that is created by using the method with a string name that is not valid. ]]> @@ -7727,7 +7727,7 @@ This example is designed to be used with a Windows Form. Paste the code into the enumeration. When the method is applied to a structure that is created by using the method, returns a string that consists of the ARGB component names and their values, even if the ARGB value matches the ARGB value of a predefined color. + A predefined color is also called a known color and is represented by an element of the enumeration. When the method is applied to a structure that is created by using the method, returns a string that consists of the ARGB component names and their values, even if the ARGB value matches the ARGB value of a predefined color. @@ -7740,7 +7740,7 @@ This example is designed to be used with a Windows Form. Paste the code into the - Uses a brush to paint rectangles. Each of the rectangles is painted a that matches the criteria stated in the first step. The name of the and its component values are also displayed. - This example displays certain known colors and uses to display the names of the colors and their four component values. + This example displays certain known colors and uses to display the names of the colors and their four component values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicColorExamples/CPP/form1.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/FromArgb/form1.cs" id="Snippet10"::: diff --git a/xml/System.Drawing/ColorConverter.xml b/xml/System.Drawing/ColorConverter.xml index bd131dc5932..f71c2889b6a 100644 --- a/xml/System.Drawing/ColorConverter.xml +++ b/xml/System.Drawing/ColorConverter.xml @@ -53,12 +53,12 @@ the expects the unqualified color name; otherwise, an exception will occur in the conversion process. For example, you should pass "Blue", not "System.Drawing.Color.Blue" or "Color.Blue", to the method. + When converting from a string to a the expects the unqualified color name; otherwise, an exception will occur in the conversion process. For example, you should pass "Blue", not "System.Drawing.Color.Blue" or "Color.Blue", to the method. ## Examples - The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowColorConverter` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowColorConverter` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Converters/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ColorConverter/Overview/form1.cs" id="Snippet2"::: @@ -277,7 +277,7 @@ the expects the unqualified color name; otherwise, an exception will occur in the conversion process. For example, you should pass "Blue", not "System.Drawing.Color.Blue" or "Color.Blue", to the method. + When converting from a string to a the expects the unqualified color name; otherwise, an exception will occur in the conversion process. For example, you should pass "Blue", not "System.Drawing.Color.Blue" or "Color.Blue", to the method. ]]> diff --git a/xml/System.Drawing/ContentAlignment.xml b/xml/System.Drawing/ContentAlignment.xml index 6d1a5081c9b..0dde88dee9a 100644 --- a/xml/System.Drawing/ContentAlignment.xml +++ b/xml/System.Drawing/ContentAlignment.xml @@ -56,15 +56,15 @@ Specifies alignment of content on the drawing surface. - and constructors and the enumeration. To run this example paste this code into a Windows Form that contains a label named `Label1` and call the `InitializeLabel1` method in the form's constructor. - + and constructors and the enumeration. To run this example paste this code into a Windows Form that contains a label named `Label1` and call the `InitializeLabel1` method in the form's constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Drawing/CopyPixelOperation.xml b/xml/System.Drawing/CopyPixelOperation.xml index 61c6d56c278..1e81c5caf3b 100644 --- a/xml/System.Drawing/CopyPixelOperation.xml +++ b/xml/System.Drawing/CopyPixelOperation.xml @@ -39,11 +39,11 @@ Determines how the source color in a copy pixel operation is combined with the destination color to result in a final color. - enumeration is used by the method of the class. - + enumeration is used by the method of the class. + ]]> How to: Copy Pixels For Reducing Flicker in Windows Forms diff --git a/xml/System.Drawing/Font.xml b/xml/System.Drawing/Font.xml index 42e874b92e2..4e62a4f009f 100644 --- a/xml/System.Drawing/Font.xml +++ b/xml/System.Drawing/Font.xml @@ -97,7 +97,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates how to use the constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller" and a named `Label1`. Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. + The following code example demonstrates how to use the constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller" and a named `Label1`. Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet1"::: @@ -155,7 +155,7 @@ operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. + The following code example demonstrates the operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet3"::: @@ -254,7 +254,7 @@ ## Examples - The following code example demonstrates how to use the constructor. This example is designed to be used with a Windows Form and requires a `e`, which is a parameter of the event. + The following code example demonstrates how to use the constructor. This example is designed to be used with a Windows Form and requires a `e`, which is a parameter of the event. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippetconstructfontwithstring"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippetconstructfontwithstring"::: @@ -562,7 +562,7 @@ ## Examples - The following code example demonstrates how to use the constructor. This example is designed to be used with Windows Forms. To run this example, paste this code into a form that contains a button named `Button2`, and associate the `Button2_Click` method with the event of the button. + The following code example demonstrates how to use the constructor. This example is designed to be used with Windows Forms. To run this example, paste this code into a form that contains a button named `Button2`, and associate the `Button2_Click` method with the event of the button. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet3"::: @@ -839,7 +839,7 @@ operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. + The following code example demonstrates the operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet3"::: @@ -938,12 +938,12 @@ allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -1434,7 +1434,7 @@ constructor. This property takes a value from the list defined in the Windows SDK header file WinGDI.h. The character sets and byte values are listed in the following table. + This property returns 1, unless a different character set is specified in the constructor. This property takes a value from the list defined in the Windows SDK header file WinGDI.h. The character sets and byte values are listed in the following table. |Character set|Value| |-------------------|-----------| @@ -1512,7 +1512,7 @@ ## Remarks Use this property to determine if a font is compatible with native Win32 controls on non-Unicode platforms. - only returns `true` if this font was created from a classic GDI + only returns `true` if this font was created from a classic GDI font definition, like a LOGFONT or HFONT. @@ -1804,7 +1804,7 @@ 2355*(0.3/2048)\*96 = 33.11719 - The value returned by the method would be 33.11719, and the value returned by the property would be 34. The property is the value returned by , rounded up to the nearest integer. + The value returned by the method would be 33.11719, and the value returned by the property would be 34. The property is the value returned by , rounded up to the nearest integer. ]]> @@ -1964,7 +1964,7 @@ constructor and the , , , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. + The following code example demonstrates how to use the constructor and the , , , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet1"::: @@ -2072,7 +2072,7 @@ constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. + The following code example demonstrates how to use the constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet1"::: @@ -2124,7 +2124,7 @@ constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. + The following code example demonstrates how to use the constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet1"::: @@ -2698,7 +2698,7 @@ constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. + The following code example demonstrates how to use the constructor and the , , and properties. This example is designed to be used with a Windows Form that contains a named `ComboBox1` that is populated with the strings "Bigger" and "Smaller". Paste the following code into the form and associate the `ComboBox1_SelectedIndexChanged` method with the event of the control. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.FontsExample/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Font/Overview/form1.cs" id="Snippet1"::: diff --git a/xml/System.Drawing/FontConverter+FontNameConverter.xml b/xml/System.Drawing/FontConverter+FontNameConverter.xml index 29da8cda66a..df2a45a8521 100644 --- a/xml/System.Drawing/FontConverter+FontNameConverter.xml +++ b/xml/System.Drawing/FontConverter+FontNameConverter.xml @@ -304,11 +304,11 @@ if the collection returned from is an exclusive list of possible values; otherwise, . The default is . - provides. - + provides. + ]]> diff --git a/xml/System.Drawing/FontConverter.xml b/xml/System.Drawing/FontConverter.xml index 9783a1ca1d4..dca84e6ebb9 100644 --- a/xml/System.Drawing/FontConverter.xml +++ b/xml/System.Drawing/FontConverter.xml @@ -53,7 +53,7 @@ class through the class by calling the method. + A type converter is used to convert values between data types. A type converter also supports property configuration at design time by providing text-to-value conversion or a list of values that users can select from. Access the class through the class by calling the method. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -110,7 +110,7 @@ object through the method. + You should access a object through the method. ]]> @@ -341,7 +341,7 @@ method of the object if the object is valid and if the destination type is string. + The most common type conversion is to and from a string type. The default implementation calls the method of the object if the object is valid and if the destination type is string. ]]> diff --git a/xml/System.Drawing/FontFamily.xml b/xml/System.Drawing/FontFamily.xml index 9d914632513..f8f3e5c2d6b 100644 --- a/xml/System.Drawing/FontFamily.xml +++ b/xml/System.Drawing/FontFamily.xml @@ -253,12 +253,12 @@ allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Drawing/Graphics+DrawImageAbort.xml b/xml/System.Drawing/Graphics+DrawImageAbort.xml index fab0c06e509..7bad770e7eb 100644 --- a/xml/System.Drawing/Graphics+DrawImageAbort.xml +++ b/xml/System.Drawing/Graphics+DrawImageAbort.xml @@ -48,53 +48,53 @@ Provides a callback method for deciding when the method should prematurely cancel execution and stop drawing an image. This method returns if it decides that the method should prematurely stop execution. Otherwise it returns to indicate that the method should continue execution. - method of the class. Certain overloads of the method call an application-defined callback method of this type to find out if the overloads should stop or continue execution. - - During execution, the relevant overloads frequently call this callback method to find out if they should stop drawing the specified image or if they should continue drawing the image. The callback method can determine whether to continue or not based on a chosen algorithm included in it, optionally using the data passed to it by the callbackdata parameter. For example, an algorithm might determine if the image has scrolled off the screen and signal a cancellation to the method to stop drawing. - - A user declaration of this event-handling method must have the same parameters as the delegate declaration. - - - -## Examples - This example is a simplistic implementation of the delegate. It merely checks to see if the method has passed it data using the callbackdata parameter. (Some overloads have only a `DrawImageAbort` parameter and pass no data; some overloads have both `DrawImageAbort` and `callbackdata` parameters and can pass data.) If no data was passed, it returns `true` to signal to the calling method that it should cancel the drawing. If data was passed, it returns `false` to signal that drawing should continue. - - A realistic implementation of this callback would involve the actual scrutiny of some criteria to cancel or continue the execution. - -```vb -Private Function DrawImageCallback(callBackData As IntPtr) As Boolean - ' Test for call that passes callBackData parameter. - If callBackData.Equals(IntPtr.Zero) Then - ' If no callBackData passed, abort DrawImage method. - Return True - Else - ' If callBackData passed, continue DrawImage method. - Return False - End If - End Function 'DrawImageCallback -``` - -```csharp -// Define DrawImageAbort callback method. - private bool DrawImageCallback(IntPtr callbackdata) - { - // Test for call that passes callBackData parameter. - if(callbackdata==IntPtr.Zero) - { - // If no callbackdata passed, cancel DrawImage method. - return true; - } - else - { - // If callbackdata passed, continue DrawImage method. - return false; - } - } -``` - + method of the class. Certain overloads of the method call an application-defined callback method of this type to find out if the overloads should stop or continue execution. + + During execution, the relevant overloads frequently call this callback method to find out if they should stop drawing the specified image or if they should continue drawing the image. The callback method can determine whether to continue or not based on a chosen algorithm included in it, optionally using the data passed to it by the callbackdata parameter. For example, an algorithm might determine if the image has scrolled off the screen and signal a cancellation to the method to stop drawing. + + A user declaration of this event-handling method must have the same parameters as the delegate declaration. + + + +## Examples + This example is a simplistic implementation of the delegate. It merely checks to see if the method has passed it data using the callbackdata parameter. (Some overloads have only a `DrawImageAbort` parameter and pass no data; some overloads have both `DrawImageAbort` and `callbackdata` parameters and can pass data.) If no data was passed, it returns `true` to signal to the calling method that it should cancel the drawing. If data was passed, it returns `false` to signal that drawing should continue. + + A realistic implementation of this callback would involve the actual scrutiny of some criteria to cancel or continue the execution. + +```vb +Private Function DrawImageCallback(callBackData As IntPtr) As Boolean + ' Test for call that passes callBackData parameter. + If callBackData.Equals(IntPtr.Zero) Then + ' If no callBackData passed, abort DrawImage method. + Return True + Else + ' If callBackData passed, continue DrawImage method. + Return False + End If + End Function 'DrawImageCallback +``` + +```csharp +// Define DrawImageAbort callback method. + private bool DrawImageCallback(IntPtr callbackdata) + { + // Test for call that passes callBackData parameter. + if(callbackdata==IntPtr.Zero) + { + // If no callbackdata passed, cancel DrawImage method. + return true; + } + else + { + // If callbackdata passed, continue DrawImage method. + return false; + } + } +``` + ]]> diff --git a/xml/System.Drawing/Graphics+EnumerateMetafileProc.xml b/xml/System.Drawing/Graphics+EnumerateMetafileProc.xml index 8540b85502c..12fd934fa97 100644 --- a/xml/System.Drawing/Graphics+EnumerateMetafileProc.xml +++ b/xml/System.Drawing/Graphics+EnumerateMetafileProc.xml @@ -57,18 +57,18 @@ Provides a callback method for the method. Return if you want to continue enumerating records; otherwise, . - method of the class. Certain overloads of the method call an application-defined callback method of this type for each record in a specified metafile. The callback function can display each record (or selected records) by calling the method of the that is being enumerated. - - A user declaration of this callback method must have the same parameters as the delegate declaration. - - - -## Examples - For an example see . - + method of the class. Certain overloads of the method call an application-defined callback method of this type for each record in a specified metafile. The callback function can display each record (or selected records) by calling the method of the that is being enumerated. + + A user declaration of this callback method must have the same parameters as the delegate declaration. + + + +## Examples + For an example see . + ]]> diff --git a/xml/System.Drawing/Graphics.xml b/xml/System.Drawing/Graphics.xml index b35f04d9a64..1f391586207 100644 --- a/xml/System.Drawing/Graphics.xml +++ b/xml/System.Drawing/Graphics.xml @@ -65,11 +65,11 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] - You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](https://learn.microsoft.com/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). + You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](https://learn.microsoft.com/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). - You can draw many different shapes and lines by using a object. For more information about how to draw lines and shapes, see the specific `Draw`*GraphicalElement* method for the line or shape you want to draw. These methods include , , , , and . For more information about how to draw lines and shapes, see [Using a Pen to Draw Lines and Shapes](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/using-a-pen-to-draw-lines-and-shapes) and [Using a Brush to Fill Shapes](https://learn.microsoft.com/dotnet/framework/winforms/advanced/using-a-brush-to-fill-shapes). + You can draw many different shapes and lines by using a object. For more information about how to draw lines and shapes, see the specific `Draw`*GraphicalElement* method for the line or shape you want to draw. These methods include , , , , and . For more information about how to draw lines and shapes, see [Using a Pen to Draw Lines and Shapes](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/using-a-pen-to-draw-lines-and-shapes) and [Using a Brush to Fill Shapes](https://learn.microsoft.com/dotnet/framework/winforms/advanced/using-a-brush-to-fill-shapes). - You can also draw images and icons by using the and methods, respectively. To perform a bit-block transfer of color data from the screen to the drawing surface of the object, see . For more information about how to draw images with a object, see [Working with Images, Bitmaps, Icons, and Metafiles](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). + You can also draw images and icons by using the and methods, respectively. To perform a bit-block transfer of color data from the screen to the drawing surface of the object, see . For more information about how to draw images with a object, see [Working with Images, Bitmaps, Icons, and Metafiles](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/images-bitmaps-and-metafiles). In addition, you can manipulate the coordinate system used by the object. For more information on the coordinate system and how to manipulate it, see [Coordinate Systems and Transformations](https://learn.microsoft.com/dotnet/framework/winforms/advanced/coordinate-systems-and-transformations). @@ -217,17 +217,17 @@ method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. + Use this method with the method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. - When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. - Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. - The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. + The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. @@ -300,19 +300,19 @@ method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. + Use this method with the method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. - When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. - Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. This method specifies a scale transformation for the new graphics container with the `dstrect` and `srcrect` parameters. The scale is equal to the transformation that, when applied to `srcrect`, results in `dstrect`. - The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. + The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. @@ -385,19 +385,19 @@ method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. + Use this method with the method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. - When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. - Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the `Save` method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the `Save` method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. This method specifies a scale transformation for the new graphics container with the `dstrect` and `srcrect` parameters. The scale is equal to the transformation that, when applied to `srcrect`, results in `dstrect`. - The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. + The graphics state established by the method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values. @@ -464,9 +464,9 @@ ## Remarks -Effectively, the method fills an area with a solid color brush of the specified color. The transparency of the specified color is maintained. +Effectively, the method fills an area with a solid color brush of the specified color. The transparency of the specified color is maintained. -This method clears the state of the graphics object and should not be called when the graphics object cannot be updated. For example, if the method is called on a secure desktop in a terminal server session, an may occur, leaving the object in an inconsistent state. +This method clears the state of the graphics object and should not be called when the graphics object cannot be updated. For example, if the method is called on a secure desktop in a terminal server session, an may occur, leaving the object in an inconsistent state. ## Examples @@ -522,7 +522,7 @@ The following code example is designed for use with Windows Forms, and it requir object returned by the property does not affect subsequent drawing with the object. To change the clip region, replace the property value with a new object. To determine whether the clipping region is infinite, retrieve the property and call its method. + Modifying the object returned by the property does not affect subsequent drawing with the object. To change the clip region, replace the property value with a new object. To determine whether the clipping region is infinite, retrieve the property and call its method. @@ -575,7 +575,7 @@ The following code example is designed for use with Windows Forms, and it requir ## Remarks The unit for resulting rectangle is designated by the property. The default unit is pixels. A is typically associated with a control and the origin of the rectangle will be relative to the client area of that control. - If the clipping region is infinite, the property returns a meaningless large rectangle. To determine whether the clipping region is infinite, retrieve the property and call its method. + If the clipping region is infinite, the property returns a meaningless large rectangle. To determine whether the clipping region is infinite, retrieve the property and call its method. ]]> @@ -719,12 +719,12 @@ The following code example is designed for use with Windows Forms, and it requir methods are useful for layering one image on top of another. To specify how the source and destination colors are blended, use one of the methods that takes a parameter. + The methods are useful for layering one image on top of another. To specify how the source and destination colors are blended, use one of the methods that takes a parameter. ## Examples - The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels1` method from the event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels1` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet4"::: @@ -780,12 +780,12 @@ The following code example is designed for use with Windows Forms, and it requir methods are useful for layering one image on top of another. The `copyPixelOperation` parameter allows you to specify if and how the source colors should be blended with the colors in the destination area. + The methods are useful for layering one image on top of another. The `copyPixelOperation` parameter allows you to specify if and how the source colors should be blended with the colors in the destination area. ## Examples - The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels2` method from the event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels2` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet5"::: @@ -851,12 +851,12 @@ The following code example is designed for use with Windows Forms, and it requir methods are useful for layering one image on top of another. To specify how the source and destination colors are blended, use one of the methods that takes a parameter. + The methods are useful for layering one image on top of another. To specify how the source and destination colors are blended, use one of the methods that takes a parameter. ## Examples - The following code example demonstrates how to use the for printing a copy of the current form. + The following code example demonstrates how to use the for printing a copy of the current form. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/CopyFromScreen/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/CopyFromScreen/Form1.vb" id="Snippet1"::: @@ -916,12 +916,12 @@ The following code example is designed for use with Windows Forms, and it requir methods are useful for layering one image on top of another. The `copyPixelOperation` parameter allows you to specify if and how the source colors should be blended with the colors in the destination area. + The methods are useful for layering one image on top of another. The `copyPixelOperation` parameter allows you to specify if and how the source colors should be blended with the colors in the destination area. ## Examples - The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels4` method from the event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `CopyPixels4` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet7"::: @@ -974,7 +974,7 @@ The following code example is designed for use with Windows Forms, and it requir allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. @@ -1042,7 +1042,7 @@ The following code example is designed for use with Windows Forms, and it requir ## Examples - The following method shows the use of the and properties. This example is designed for use with a Windows Form. To run this example, paste it into a form that contains a named listBox1 and call this method from the form's constructor. + The following method shows the use of the and properties. This example is designed for use with a Windows Form. To run this example, paste it into a form that contains a named listBox1 and call this method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet4"::: @@ -1096,7 +1096,7 @@ The following code example is designed for use with Windows Forms, and it requir ## Examples - The following method shows the use of the and properties. This example is designed for use with a Windows Form. To run this example, paste it into a form that contains a named listBox1 and call this method from the form's constructor. + The following method shows the use of the and properties. This example is designed for use with a Windows Form. To run this example, paste it into a form that contains a named listBox1 and call this method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet4"::: @@ -4431,7 +4431,7 @@ The object has a transform applied othe ## Remarks An stores a value for pixel width and a value for horizontal resolution (dots per inch). The physical width, measured in inches, of an image is the pixel width divided by the horizontal resolution. For example, an image with a pixel width of 216 and a horizontal resolution of 72 dots per inch has a physical width of 3 inches. Similar remarks apply to pixel height and physical height. - The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. + The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. @@ -5495,7 +5495,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method: @@ -5517,7 +5517,7 @@ The object has a transform applied othe For the original, unadjusted parallelogram, the position locates the image on the screen, and the size of the rectangle and the size and shape of the parallelogram determines the scaling and shearing of the drawn image. - Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. + Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet38"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet38"::: @@ -5613,7 +5613,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -5635,7 +5635,7 @@ The object has a transform applied othe For the original, unadjusted parallelogram, the position locates the image on the screen, and the size of the rectangle and the size and shape of the parallelogram determines the scaling and shearing of the drawn image. - Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. + Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet44"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet44"::: @@ -5727,7 +5727,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -5749,7 +5749,7 @@ The object has a transform applied othe For the original, unadjusted parallelogram, the position locates the image on the screen, and the size of the rectangle and the size and shape of the parallelogram determines the scaling and shearing of the drawn image. - Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. + Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet39"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet39"::: @@ -5839,7 +5839,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the `Pa` event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the `Pa` event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -5861,7 +5861,7 @@ The object has a transform applied othe For the original, unadjusted parallelogram, the position locates the image on the screen, and the size of the rectangle and the size and shape of the parallelogram determines the scaling and shearing of the drawn image. - Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. + Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet45"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet45"::: @@ -6338,7 +6338,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -6360,7 +6360,7 @@ The object has a transform applied othe For the original, unadjusted destination rectangle, the position locates the image on the screen, and the size of the source rectangle and the size and shape of the destination rectangle determines the scaling of the drawn image. - Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. + Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet50"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet50"::: @@ -6447,7 +6447,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -6469,7 +6469,7 @@ The object has a transform applied othe For the original, unadjusted destination rectangle, the position locates the image on the screen, and the size of the source rectangle and the size and shape of the destination rectangle determines the scaling of the drawn image. - Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. + Because this example uses an overload that does not pass a `callBackData` parameter, the callback returns `true`, which causes the method to end, and the exception-handling code included in the example prints out the exception text rather than drawing the image. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet54"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet54"::: @@ -6558,7 +6558,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -6580,7 +6580,7 @@ The object has a transform applied othe For the original, unadjusted destination rectangle, the position locates the image on the screen, and the size of the source rectangle and the size and shape of the destination rectangle determines the scaling of the drawn image. - Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. + Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples/CPP/form1.cpp" id="Snippet51"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Overview/form1.cs" id="Snippet51"::: @@ -6669,7 +6669,7 @@ The object has a transform applied othe ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code first defines a callback method for the delegate; the definition is simplistic and merely tests to see whether the method calls it with a null `callBackData` parameter. The main body of the example performs the following actions: - Creates an instance of the callback method. @@ -6691,7 +6691,7 @@ The object has a transform applied othe For the original, unadjusted destination rectangle, the position locates the image on the screen, and the size of the source rectangle and the size and shape of the destination rectangle determines the scaling of the drawn image. - Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. + Because this example uses an overload that passes a `callBackData` parameter, the callback returns `false`, which causes the method to continue, and the example draws the adjusted image to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicGraphicsExamples2/CPP/form1.cpp" id="Snippet55"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/DrawImage/form1.cs" id="Snippet55"::: @@ -6758,7 +6758,7 @@ The object has a transform applied othe ## Remarks An stores a value for pixel width and a value for horizontal resolution (dots per inch). The physical width, measured in inches, of an image is the pixel width divided by the horizontal resolution. For example, an image with a pixel width of 216 and a horizontal resolution of 72 dots per inch has a physical width of 3 inches. Similar remarks apply to pixel height and physical height. - The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. + The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. @@ -6826,7 +6826,7 @@ The object has a transform applied othe ## Remarks An stores a value for pixel width and a value for horizontal resolution (dots per inch). The physical width, measured in inches, of an image is the pixel width divided by the horizontal resolution. For example, an image with a pixel width of 216 and a horizontal resolution of 72 dots per inch has a physical width of 3 inches. Similar remarks apply to pixel height and physical height. - The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. + The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. ]]> @@ -6886,7 +6886,7 @@ The object has a transform applied othe ## Remarks An stores a value for pixel width and a value for horizontal resolution (dots per inch). The physical width, measured in inches, of an image is the pixel width divided by the horizontal resolution. For example, an image with a pixel width of 216 and a horizontal resolution of 72 dots per inch has a physical width of 3 inches. Similar remarks apply to pixel height and physical height. - The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. + The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. @@ -6965,7 +6965,7 @@ The object has a transform applied othe ## Remarks An stores a value for pixel width and a value for horizontal resolution (dots per inch). The physical width, measured in inches, of an image is the pixel width divided by the horizontal resolution. For example, an image with a pixel width of 216 and a horizontal resolution of 72 dots per inch has a physical width of 3 inches. Similar remarks apply to pixel height and physical height. - The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. + The method draws an image using its physical size, so the image will have its correct size in inches regardless of the resolution (dots per inch) of the display device. For example, suppose an image has a pixel width of 216 and a horizontal resolution of 72 dots per inch. If you call to draw that image on a device that has a resolution of 96 dots per inch, the pixel width of the rendered image will be (216/72)*96 = 288. ]]> @@ -7013,7 +7013,7 @@ The object has a transform applied othe method. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawImageUnscaled` method from the event-handling method, passing `e` as . + The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawImageUnscaled` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet8"::: @@ -8279,7 +8279,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see . @@ -8383,7 +8383,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see . @@ -8453,7 +8453,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see . @@ -9052,7 +9052,7 @@ The object has a transform applied othe overload that takes a . + The text represented by the `s` parameter is drawn inside the rectangle represented by the `layoutRectangle` parameter. If the text does not fit inside the rectangle, it is truncated at the nearest word. To further manipulate how the string is drawn inside the rectangle use the overload that takes a . @@ -9715,15 +9715,15 @@ The object has a transform applied othe method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. + Use this method with the method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties. - When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying object to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. - Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Containers can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as an method call is paired with a method call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. @@ -9805,14 +9805,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - The following code example creates a form that has a as one of its private members. The method calls , which calls the form's `MetafileCallback` method for each record in the metafile. The `MetafileCallback` method calls the method. Notice that the `MetafileCallback` method receives the record data as an , but the method expects the record data to be a byte array. The call to copies the record data to a byte array so that it can be passed to . + The following code example creates a form that has a as one of its private members. The method calls , which calls the form's `MetafileCallback` method for each record in the metafile. The `MetafileCallback` method calls the method. Notice that the `MetafileCallback` method receives the record data as an , but the method expects the record data to be a byte array. The call to copies the record data to a byte array so that it can be passed to . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/EnumerateMetafile/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Graphics/EnumerateMetafile/Form1.vb" id="Snippet1"::: @@ -9867,14 +9867,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -9927,14 +9927,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -9986,16 +9986,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10048,14 +10048,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10108,14 +10108,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10176,14 +10176,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10243,14 +10243,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10310,14 +10310,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10371,16 +10371,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10441,14 +10441,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10509,14 +10509,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10582,14 +10582,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10647,14 +10647,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10718,9 +10718,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -10729,7 +10729,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10786,9 +10786,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -10797,7 +10797,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10862,16 +10862,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The image attributes specified by the `imageAttr` parameter replace those specified when the metafile was written. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -10929,16 +10929,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11002,9 +11002,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -11013,7 +11013,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11070,9 +11070,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -11081,7 +11081,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11147,16 +11147,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The image attributes specified by the `imageAttr` parameter replace those specified when the metafile was written. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11214,16 +11214,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11289,16 +11289,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The image attributes specified by the `imageAttr` parameter replace those specified when the metafile was written. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11356,16 +11356,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11431,14 +11431,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11503,9 +11503,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -11514,7 +11514,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11580,16 +11580,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11654,9 +11654,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -11665,7 +11665,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11731,16 +11731,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11806,16 +11806,16 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the`callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11886,14 +11886,14 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. ## Examples - For a code example, see . + For a code example, see . ]]> @@ -11962,9 +11962,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -11975,7 +11975,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -12046,9 +12046,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. @@ -12057,7 +12057,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -12126,9 +12126,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. The `destPoints` parameter specifies three points of a parallelogram. The three structures represent the upper-left, upper-right, and lower-left corners of the parallelogram. The fourth point is extrapolated from the first three to form a parallelogram. The drawn metafile is scaled and sheared to fit the parallelogram. @@ -12139,7 +12139,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -12210,9 +12210,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. @@ -12221,7 +12221,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -12292,9 +12292,9 @@ The object has a transform applied othe method to "play back", or draw, the record. + This method enumerates the records contained in the specified metafile. Each record is individually sent to a callback method specified by the `callback` parameter. Typically, the callback method calls the method to "play back", or draw, the record. - If the callback method calls , it must do so by calling the method of the specific that is being enumerated. + If the callback method calls , it must do so by calling the method of the specific that is being enumerated. Any drawing that takes place outside of the rectangle specified by the `srcRect` parameter is ignored. @@ -12303,7 +12303,7 @@ The object has a transform applied othe ## Examples - For a code example, see . + For a code example, see . ]]> @@ -15237,11 +15237,11 @@ The object has a transform applied othe method to release the and related resources created by the method. + You should always call the method to release the and related resources created by the method. Even if the display device has an associated ICM color profile, GDI+ will not use that profile by default. To enable ICM for a , construct the from an HDC after you pass the HDC (and ICM_ON) to the `SetICMMode` function. Then any drawing done by the will be adjusted according to the ICM profile associated with the display device. Enabling ICM will result in slower performance. - The state of the device context (mapping mode, logical unit, and the like) at the time you call can affect rendering done by the . + The state of the device context (mapping mode, logical unit, and the like) at the time you call can affect rendering done by the . @@ -15312,11 +15312,11 @@ The object has a transform applied othe method to release the and related resources created by the method. + You should always call the method to release the and related resources created by the method. Even if the display device has an associated ICM color profile, GDI+ will not use that profile by default. To enable ICM for a , construct the from an HDC after you pass the HDC (and ICM_ON) to the `SetICMMode` function. Then any drawing done by the will be adjusted according to the ICM profile associated with the display device. Enabling ICM will result in slower performance. - The state of the device context (mapping mode, logical unit, and the like) at the time you call can affect rendering done by the . + The state of the device context (mapping mode, logical unit, and the like) at the time you call can affect rendering done by the . The device handle is typically used to query specific printer capabilities. @@ -15422,7 +15422,7 @@ The object has a transform applied othe method to release the and related resources created by the method. + You should always call the method to release the and related resources created by the method. @@ -15546,7 +15546,7 @@ The object has a transform applied othe - - You can save the indexed image as another format by using the method and then retrieve a object for the new image. + You can save the indexed image as another format by using the method and then retrieve a object for the new image. This method also throws an exception if the image has any of the following pixel formats. @@ -15558,7 +15558,7 @@ The object has a transform applied othe - - You should always call the method to release the and related resources created by the method. + You should always call the method to release the and related resources created by the method. @@ -15769,7 +15769,7 @@ The object has a transform applied othe method is to enable GDI+ to produce a better quality halftone when the display uses 8 bits per pixel. To display an image using the halftone palette, use the following procedure. + The purpose of the method is to enable GDI+ to produce a better quality halftone when the display uses 8 bits per pixel. To display an image using the halftone palette, use the following procedure. @@ -15851,9 +15851,9 @@ The object has a transform applied othe method using a handle returned from the method will fail. + The device context is a Windows structure based on GDI that defines a set of graphical objects and their associated attributes, as well as the graphical modes that affect output. This method returns that device context with the exception of a font. Because a font is not selected, calls to the method using a handle returned from the method will fail. - Calls to the and methods must appear in pairs. During the scope of a and method pair, you usually make only calls to GDI functions. Calls in that scope made to GDI+ methods of the that produced the `hdc` parameter fail with an `ObjectBusy` error. Also, GDI+ ignores any state changes made to the of the `hdc` parameter in subsequent operations. + Calls to the and methods must appear in pairs. During the scope of a and method pair, you usually make only calls to GDI functions. Calls in that scope made to GDI+ methods of the that produced the `hdc` parameter fail with an `ObjectBusy` error. Also, GDI+ ignores any state changes made to the of the `hdc` parameter in subsequent operations. @@ -15866,7 +15866,7 @@ The object has a transform applied othe - Creates a red pen. -- With the pen, draws a rectangle to the screen using the GDI+ method. +- With the pen, draws a rectangle to the screen using the GDI+ method. - Defines an internal pointer type variable `hdc` and sets its value to the handle to the device context of the form. @@ -17033,7 +17033,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17211,7 +17211,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17295,9 +17295,9 @@ The object has a transform applied othe structure (). If the `width` parameter is less than the actual width of the string, the returned component is truncated to a value representing the maximum number of characters that will fit within the specified width. To accommodate the entire string, the returned component is adjusted to a value that allows displaying the string with character wrap. + The `width` parameter specifies the maximum value of the width component of the returned structure (). If the `width` parameter is less than the actual width of the string, the returned component is truncated to a value representing the maximum number of characters that will fit within the specified width. To accommodate the entire string, the returned component is adjusted to a value that allows displaying the string with character wrap. - The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17541,7 +17541,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17635,7 +17635,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17726,7 +17726,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a , and pass . Also, ensure the for the is . @@ -17880,7 +17880,7 @@ The object has a transform applied othe method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a and pass . Also ensure the for the is . + The method is designed for use with individual strings and includes a small amount of extra space before and after the string to allow for overhanging glyphs. Also, the method adjusts glyph points to optimize display quality and might display a string narrower than reported by . To obtain metrics suitable for adjacent strings in layout (for example, when implementing formatted text), use the method or one of the methods that takes a and pass . Also ensure the for the is . @@ -18156,7 +18156,7 @@ The object has a transform applied othe and members to change the scale and origin when you draw a rectangle. + The following code example demonstrates how to use the and members to change the scale and origin when you draw a rectangle. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangePageScaleAndTranslateTransform` method when handling the form's event, passing `e` as . @@ -18314,7 +18314,7 @@ The object has a transform applied othe and are two methods that allow you to get and release the handle for a Windows device. You should always follow a call to with a call to when you are finished with the Windows handle. + and are two methods that allow you to get and release the handle for a Windows device. You should always follow a call to with a call to when you are finished with the Windows handle. ]]> @@ -18368,7 +18368,7 @@ The object has a transform applied othe ## Remarks The device context is a Windows structure based on GDI that defines a set of graphical objects and their associated attributes, as well as the graphical modes that affect output. - Calls to the and methods must appear in pairs. During the scope of a and method pair, you usually make calls only to GDI functions. Calls in that scope made to GDI+ methods of the that produced the `hdc` parameter fail with an `ObjectBusy` error. Also, GDI+ ignores any state changes made to the of the `hdc` parameter in subsequent operations. + Calls to the and methods must appear in pairs. During the scope of a and method pair, you usually make calls only to GDI functions. Calls in that scope made to GDI+ methods of the that produced the `hdc` parameter fail with an `ObjectBusy` error. Also, GDI+ ignores any state changes made to the of the `hdc` parameter in subsequent operations. @@ -18379,7 +18379,7 @@ The object has a transform applied othe - Creates a red pen. -- With the pen, draws a rectangle to the screen using the GDI+ method. +- With the pen, draws a rectangle to the screen using the GDI+ method. - Defines an internal pointer type variable `hdc` and sets its value to the handle to the device context of the form. @@ -18642,13 +18642,13 @@ The object has a transform applied othe method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. Note that the returned by a given call to the method can be passed only once to the `Restore` method. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. Note that the returned by a given call to the method can be passed only once to the `Restore` method. - Calls to the method can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Calls to the method can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as a call is paired with a call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as a call is paired with a call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, when you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. @@ -18847,13 +18847,13 @@ The object has a transform applied othe method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. Note that the returned by a given call to the method can be passed only once to the method. + When you call the method of a , an information block that holds the state of the is put on a stack. The method returns a that identifies that information block. When you pass the identifying to the method, the information block is removed from the stack and is used to restore the to the state it was in at the time of the method call. Note that the returned by a given call to the method can be passed only once to the method. - Calls to the method can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. + Calls to the method can be nested; that is, you can call the method several times before you call the method. Each time you call the method, an information block is put on the stack, and you receive a for the information block. When you pass one of those objects to the method, the is returned to the state it was in at the time of the method call that returned that particular . The information block placed on the stack by that method call is removed from the stack, and all information blocks placed on that stack after that method call are also removed. - Calls to the method place information blocks on the same stack as calls to the method. Just as a call is paired with a call, a method call is paired with a method call. + Calls to the method place information blocks on the same stack as calls to the method. Just as a call is paired with a call, a method call is paired with a method call. - When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. + When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. Likewise, When you call the method, all information blocks placed on the stack (by the method or by the method) after the corresponding call to the method are removed from the stack. @@ -19643,7 +19643,7 @@ The object has a transform applied othe ## Examples - The following method demonstrates the effects of setting the , , and properties. The output of the example is shown in the following illustration. + The following method demonstrates the effects of setting the , , and properties. The output of the example is shown in the following illustration. ![Lines with and without smoothing applied.](~/add/media/gdi-smoothingmode.png "Lines with and without smoothing applied.") @@ -19698,7 +19698,7 @@ The object has a transform applied othe ## Examples - The following code example demonstrates the use of the and properties. + The following code example demonstrates the use of the and properties. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangeTextRenderingHintAndTextContrast` method when handling the form's event, passing `e` as . @@ -19754,7 +19754,7 @@ The object has a transform applied othe ## Examples - The following code example demonstrates the use of the and properties. + The following code example demonstrates the use of the and properties. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangeTextRenderingHintAndTextContrast` method when handling the form's event, passing `e` as . @@ -20292,7 +20292,7 @@ This is a more performant alternative to , prepending the translation to the transformation matrix. +- Moves the origin of the graphics object by calling , prepending the translation to the transformation matrix. - Draws a translated, rotated ellipse with a blue pen. @@ -20362,7 +20362,7 @@ This is a more performant alternative to , appending the translation to the world transformation matrix. +- Moves the graphics object's origin by calling , appending the translation to the world transformation matrix. - Draws a rotated, translated ellipse with a blue pen. diff --git a/xml/System.Drawing/GraphicsUnit.xml b/xml/System.Drawing/GraphicsUnit.xml index 4e095350822..c32fd34fa1a 100644 --- a/xml/System.Drawing/GraphicsUnit.xml +++ b/xml/System.Drawing/GraphicsUnit.xml @@ -40,17 +40,17 @@ Specifies the unit of measure for the given data. - handle, using the enumeration, and the use of the method to draw the rectangle bounds of a bitmap. - - This example is designed to be used with Windows Forms. Create a form that contains a button named Button2. Paste the code into the form and associate this method with the button's event. - + handle, using the enumeration, and the use of the method to draw the rectangle bounds of a bitmap. + + This example is designed to be used with Windows Forms. Create a form that contains a button named Button2. Paste the code into the form and associate this method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Drawing/IDeviceContext.xml b/xml/System.Drawing/IDeviceContext.xml index 5b5326241af..90784acc68a 100644 --- a/xml/System.Drawing/IDeviceContext.xml +++ b/xml/System.Drawing/IDeviceContext.xml @@ -36,11 +36,11 @@ Defines methods for obtaining and releasing an existing handle to a Windows device context. - interface is the class. - + interface is the class. + ]]> @@ -78,13 +78,13 @@ Returns the handle to a Windows device context. An representing the handle of a device context. - and are two methods that allow you to get and release the handle for a Windows-based device. You should always follow a call to with a call to when you are finished with the Windows handle. - - is not designed to obtain handles created using Windows GDI methods such as `CreateDC` or `CreateCompatibleDC`. - + and are two methods that allow you to get and release the handle for a Windows-based device. You should always follow a call to with a call to when you are finished with the Windows handle. + + is not designed to obtain handles created using Windows GDI methods such as `CreateDC` or `CreateCompatibleDC`. + ]]> @@ -121,11 +121,11 @@ Releases the handle of a Windows device context. - and are two methods that allow you to get and release the handle for a Windows-based device. You should always follow a call to with a call to when you are finished with the Windows handle. - + and are two methods that allow you to get and release the handle for a Windows-based device. You should always follow a call to with a call to when you are finished with the Windows handle. + ]]> diff --git a/xml/System.Drawing/Icon.xml b/xml/System.Drawing/Icon.xml index e16bce51e50..6661c0f9ae7 100644 --- a/xml/System.Drawing/Icon.xml +++ b/xml/System.Drawing/Icon.xml @@ -92,7 +92,7 @@ objects from files, streams, or embedded resources. For a list of constructors, see . You can also convert an to a bitmap by using the method. + You can construct objects from files, streams, or embedded resources. For a list of constructors, see . You can also convert an to a bitmap by using the method. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -105,7 +105,7 @@ - 48 pixels x 48 pixels ## Examples - The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's event handler, passing `e` as . + The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's event handler, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet9"::: @@ -276,7 +276,7 @@ that has a single size, this method only creates a duplicate icon. Use the stretching capabilities of the method to resize the icon. + If a version cannot be found that exactly matches the size, the closest match is used. If the `original` parameter is an that has a single size, this method only creates a duplicate icon. Use the stretching capabilities of the method to resize the icon. ]]> @@ -411,7 +411,7 @@ ## Examples - The following code example demonstrates how to use the constructor. To run this example, paste the code into a Windows Form and handle the form's event. Call the `ConstructAnIconFromAType` method from the event handler, passing `e` as . + The following code example demonstrates how to use the constructor. To run this example, paste the code into a Windows Form and handle the form's event. Call the `ConstructAnIconFromAType` method from the event handler, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet3"::: @@ -461,12 +461,12 @@ that has a single size, this method only creates a duplicate icon. Use the stretching capabilities of the method to resize the icon. + If a version cannot be found that exactly matches the size, the closest match is used. If the `original` parameter is an that has a single size, this method only creates a duplicate icon. Use the stretching capabilities of the method to resize the icon. ## Examples - The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's event handler, passing `e` as . + The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's event handler, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet9"::: @@ -703,12 +703,12 @@ ## Remarks A relative path is assumed to be relative to the current working directory. - When is used with bitmaps, a thumbnail image may be returned instead of an icon if the system that is running the application has a registry setting that causes bitmap files to be shown as thumbnail images. + When is used with bitmaps, a thumbnail image may be returned instead of an icon if the system that is running the application has a registry setting that causes bitmap files to be shown as thumbnail images. ## Examples - The following code example demonstrates how to use the method. To run this example, paste the code into a Windows Form and call `ExtractAssociatedIconEx` from the form's constructor or event handler. + The following code example demonstrates how to use the method. To run this example, paste the code into a Windows Form and call `ExtractAssociatedIconEx` from the form's constructor or event handler. :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet2"::: @@ -904,7 +904,7 @@ - Gets an icon handle for the . -- Sets the attribute of the form to an icon created from the handle. +- Sets the attribute of the form to an icon created from the handle. - Calls the Windows API function `DestroyIcon` to release resources. @@ -958,7 +958,7 @@ handle using the enumeration and how to use the method to draw the rectangle bounds of a bitmap. + The following code example demonstrates how to load a bitmap from an handle using the enumeration and how to use the method to draw the rectangle bounds of a bitmap. This example is designed to be used with Windows Forms. Create a form that contains a button named `Button2`. Paste the code into the form and associate this method with the button's event. @@ -1176,7 +1176,7 @@ The transparent areas of the icon are lost when it is converted to a bitmap, and the transparent color of the resulting bitmap is set to `RGB(13,11,12)`. The returned bitmap has the same height and width as the original icon. ## Examples - The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's . event handler, passing `e` as . + The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `IconToBitmap` method in the form's . event handler, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet9"::: diff --git a/xml/System.Drawing/IconConverter.xml b/xml/System.Drawing/IconConverter.xml index 1e1ddaec774..e62ca3ed452 100644 --- a/xml/System.Drawing/IconConverter.xml +++ b/xml/System.Drawing/IconConverter.xml @@ -330,7 +330,7 @@ method on the object if the object is valid and if the destination type is `string`. If this method cannot convert to the destination type, it throws a exception. + The default implementation calls the method on the object if the object is valid and if the destination type is `string`. If this method cannot convert to the destination type, it throws a exception. ]]> diff --git a/xml/System.Drawing/Image.xml b/xml/System.Drawing/Image.xml index 46c84e5faaf..d7a0dba9a2f 100644 --- a/xml/System.Drawing/Image.xml +++ b/xml/System.Drawing/Image.xml @@ -97,7 +97,7 @@ on a Windows Form, use one of the methods. + To draw an on a Windows Form, use one of the methods. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -172,7 +172,7 @@ ## Remarks > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -217,12 +217,12 @@ method allows the resources used by this to be reallocated for other purposes. + Calling the method allows the resources used by this to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -270,7 +270,7 @@ ## Remarks > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -507,7 +507,7 @@ ## Examples - The following code example demonstrates how to use the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . + The following code example demonstrates how to use the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet7"::: @@ -592,7 +592,7 @@ ## Examples - The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a . + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a . This example is designed to be used with Windows Forms. Create a form containing a button named `Button2`. Paste the code into the form and associate the `Button2_Click` method with the button's event. @@ -662,7 +662,7 @@ method makes a copy of the GDI bitmap; so you can release the incoming GDI bitmap using the GDI `DeleteObject` method immediately after creating the new . + The method makes a copy of the GDI bitmap; so you can release the incoming GDI bitmap using the GDI `DeleteObject` method immediately after creating the new . ]]> @@ -710,7 +710,7 @@ method makes a copy of the GDI bitmap; so you can release the incoming GDI bitmap using the GDI `DeleteObject` method immediately after creating the new . + The method makes a copy of the GDI bitmap; so you can release the incoming GDI bitmap using the GDI `DeleteObject` method immediately after creating the new . ]]> @@ -953,7 +953,7 @@ handle, using the enumeration, and how to use the method to draw the rectangle bounds of a bitmap. + The following code example demonstrates how to load a bitmap from an handle, using the enumeration, and how to use the method to draw the rectangle bounds of a bitmap. This example is designed to be used with Windows Forms. Create a form that contains a button named `Button2`. Paste the code into the form and associate this method with the button's event. @@ -1135,14 +1135,14 @@ . + For a list of property item IDs and links to more information, see . - It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . ## Examples - The following code example demonstrates how to use the and methods. This example calls passing an ID value. For a list of ID values see, . This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . + The following code example demonstrates how to use the and methods. This example calls passing an ID value. For a list of ID values see, . This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet7"::: @@ -1211,7 +1211,7 @@ ## Remarks If the contains an embedded thumbnail image, this method retrieves the embedded thumbnail and scales it to the requested size. If the does not contain an embedded thumbnail image, this method creates a thumbnail image by scaling the main image. - The method works well when the requested thumbnail image has a size of about 120 x 120 pixels. If you request a large thumbnail image (for example, 300 x 300) from an that has an embedded thumbnail, there could be a noticeable loss of quality in the thumbnail image. It might be better to scale the main image (instead of scaling the embedded thumbnail) by calling the method. + The method works well when the requested thumbnail image has a size of about 120 x 120 pixels. If you request a large thumbnail image (for example, 300 x 300) from an that has an embedded thumbnail, there could be a noticeable loss of quality in the thumbnail image. It might be better to scale the main image (instead of scaling the embedded thumbnail) by calling the method. @@ -1279,7 +1279,7 @@ and methods to recolor the image. It also uses the and properties. + The following code example demonstrates how to construct a new bitmap from a file, using the and methods to recolor the image. It also uses the and properties. This example is designed to be used with a Windows Forms that contains a , , and named `Label1`, `PictureBox1`, and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. @@ -1599,7 +1599,7 @@ and methods to recolor the image. It also uses the property. + The following code example demonstrates how to construct a new bitmap from a file, using the and methods to recolor the image. It also uses the property. This example is designed to be used with a Windows Form that contains a , and named `Label1`, `PictureBox1`, and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. @@ -1702,7 +1702,7 @@ returns an empty array (that is, an array of length zero). + If the image has no property items or if the image format does not support property items, returns an empty array (that is, an array of length zero). @@ -1794,7 +1794,7 @@ class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . ]]> @@ -1844,14 +1844,14 @@ method rotates the image clockwise. + The method rotates the image clockwise. If you wish to draw on an image once it has been rotated, you should always retrieve a new graphics object from the image, otherwise an exception could occur. ## Examples - The following code example demonstrates how to call the method on an and the enumeration. + The following code example demonstrates how to call the method on an and the enumeration. This example is designed to be used with a Windows Form that contains a named `PictureBox1` and a button named `Button1`. Paste the code into a form, call `InitializeBitmap` from the form's constructor, and associate `Button1_Click` with the button's event. Ensure the file path to the bitmap is valid on your system. @@ -1911,14 +1911,14 @@ method to save a graphic image as a Windows Metafile Format (WMF) or Enhanced Metafile Format (EMF) file, the resulting file is saved as a Portable Network Graphics (PNG) file. This behavior occurs because the GDI+ component of the .NET Framework does not have an encoder that you can use to save files as .wmf or .emf files. + If no encoder exists for the file format of the image, the Portable Network Graphics (PNG) encoder is used. When you use the method to save a graphic image as a Windows Metafile Format (WMF) or Enhanced Metafile Format (EMF) file, the resulting file is saved as a Portable Network Graphics (PNG) file. This behavior occurs because the GDI+ component of the .NET Framework does not have an encoder that you can use to save files as .wmf or .emf files. Saving the image to the same file it was constructed from is not allowed and throws an exception. ## Examples - The following code example demonstrates how to call the method. This example is designed to be used with Windows Forms. Create a form that contains a button named `Button5`. Paste the code into the form, and associate the method with the button's event. + The following code example demonstrates how to call the method. This example is designed to be used with Windows Forms. Create a form that contains a button named `Button5`. Paste the code into the form, and associate the method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet5"::: @@ -2028,7 +2028,7 @@ method. To run this example, paste the code into a Windows Form. Handle the form's event, and call the `ConstructFromResourceSaveAsGif` method, passing `e` as + The following code example demonstrates how to construct a bitmap from a type, and how to use the method. To run this example, paste the code into a Windows Form. Handle the form's event, and call the `ConstructFromResourceSaveAsGif` method, passing `e` as :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BmpCtorAndSave/cpp/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form11.cs" id="Snippet1"::: @@ -2323,7 +2323,7 @@ ## Remarks The possible values of the `dimensionID` parameter are properties of the . These can be used to identify an image by its time, resolution, or page number. - Calling this method causes all changes made to the previous frame to be discarded. Before selecting another frame, save all changes made to the current frame, including changes to pixel values and properties. If the call to the method is successful (an exception does not occur), the method will return 0. + Calling this method causes all changes made to the previous frame to be discarded. Before selecting another frame, save all changes made to the current frame, including changes to pixel values and properties. If the call to the method is successful (an exception does not occur), the method will return 0. ]]> @@ -2370,12 +2370,12 @@ ## Remarks If the image format does not support property items, this method throws with the message "Property not supported." If the image format supports property items but does not support the particular property you are attempting to set, this method ignores the attempt but does not throw an exception. - It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . ## Examples - The following code example demonstrates how to use the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . + The following code example demonstrates how to use the and methods. This example is designed to be used with Windows Forms. To run this example, paste it into a form, and handle the form's event by calling the `DemonstratePropertyItem` method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet7"::: @@ -2631,7 +2631,7 @@ from a file, using the and methods to recolor the image. It also uses the , , and properties. + The following code example demonstrates how to construct a new from a file, using the and methods to recolor the image. It also uses the , , and properties. This example is designed to be used with a Windows Forms that contains a , and named `Label1`, `PictureBox1` and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. diff --git a/xml/System.Drawing/ImageConverter.xml b/xml/System.Drawing/ImageConverter.xml index 0016b60a693..2947c058f38 100644 --- a/xml/System.Drawing/ImageConverter.xml +++ b/xml/System.Drawing/ImageConverter.xml @@ -131,11 +131,11 @@ Determines whether this can convert an instance of a specified type to an , using the specified context. This method returns if this can perform the conversion; otherwise, . - @@ -190,11 +190,11 @@ Determines whether this can convert an to an instance of a specified type, using the specified context. This method returns if this can perform the conversion; otherwise, . - @@ -315,11 +315,11 @@ Converts an (or an object that can be cast to an ) to the specified type. This method returns the converted object. - method of the object if the object is valid and if the destination type is string. If this method cannot convert the specified object to the destination type, it throws a exception. - + method of the object if the object is valid and if the destination type is string. If this method cannot convert the specified object to the destination type, it throws a exception. + ]]> The conversion cannot be completed. @@ -389,11 +389,11 @@ Gets the set of properties for this type. The set of properties that should be exposed for this data type. If no properties should be exposed, this can return . The default implementation always returns . - method for the correct data type. - + method for the correct data type. + ]]> diff --git a/xml/System.Drawing/ImageFormatConverter.xml b/xml/System.Drawing/ImageFormatConverter.xml index ecbfe1da1e2..09fb3c9fe8c 100644 --- a/xml/System.Drawing/ImageFormatConverter.xml +++ b/xml/System.Drawing/ImageFormatConverter.xml @@ -51,16 +51,16 @@ is a class that can be used to convert objects from one data type to another. Access this class through the object. - class through the class by calling the method. - - The converts to and from known image formats, as specified in the class. - + class through the class by calling the method. + + The converts to and from known image formats, as specified in the class. + > [!NOTE] -> If you want to convert between image formats, such as converting between BMP and JPEG, use one of the methods that takes an object as a parameter. - +> If you want to convert between image formats, such as converting between BMP and JPEG, use one of the methods that takes an object as a parameter. + ]]> @@ -104,11 +104,11 @@ Initializes a new instance of the class. - object directly. Access the class through the class by calling the method. - + object directly. Access the class through the class by calling the method. + ]]> @@ -164,11 +164,11 @@ Indicates whether this converter can convert an object in the specified source type to the native type of the converter. This method returns if this object can perform the conversion. - converts to and from known image formats, as specified in the class. - + converts to and from known image formats, as specified in the class. + ]]> @@ -223,11 +223,11 @@ Gets a value indicating whether this converter can convert an object to the specified destination type using the context. This method returns if this object can perform the conversion. - converts to and from known image formats, as specified in the class. - + converts to and from known image formats, as specified in the class. + ]]> @@ -285,11 +285,11 @@ Converts the specified object to an object. The converted object. - converts to and from known image formats, as specified in the class. - + converts to and from known image formats, as specified in the class. + ]]> The conversion cannot be completed. @@ -350,13 +350,13 @@ Converts the specified object to the specified type. The converted object. - converts to and from known image formats, as specified in the class. - - The most common type conversion is to and from a string type. The default implementation calls the method of the object if the object is valid and if the destination type is `string`. If this method cannot convert the specified object to the specified destination type, it throws a exception. - + converts to and from known image formats, as specified in the class. + + The most common type conversion is to and from a string type. The default implementation calls the method of the object if the object is valid and if the destination type is `string`. If this method cannot convert the specified object to the specified destination type, it throws a exception. + ]]> The conversion cannot be completed. diff --git a/xml/System.Drawing/Pen.xml b/xml/System.Drawing/Pen.xml index 5278174d0f0..48153a184ca 100644 --- a/xml/System.Drawing/Pen.xml +++ b/xml/System.Drawing/Pen.xml @@ -56,7 +56,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates constructing a with a and the effects of setting the property on a . + The following code example demonstrates constructing a with a and the effects of setting the property on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -126,7 +126,7 @@ ## Examples - The following code example demonstrates constructing a with a and the effects of setting the property on a . + The following code example demonstrates constructing a with a and the effects of setting the property on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -235,7 +235,7 @@ ## Examples - The following code example creates a and demonstrates the effects of setting the and properties on a . + The following code example creates a and demonstrates the effects of setting the and properties on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowStartAndEndCaps` method when handling the form's event, passing `e` as . @@ -292,7 +292,7 @@ ## Examples - The following code example demonstrates creating a and the effects of setting the , , and properties. + The following code example demonstrates creating a and the effects of setting the , , and properties. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowPensAndSmoothingMode` method when handling the form's event, passing e as . @@ -645,7 +645,7 @@ ## Examples - The following code example demonstrates creating a and the effects of setting the , , and properties. + The following code example demonstrates creating a and the effects of setting the , , and properties. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowPensAndSmoothingMode` method when handling the form's event, passing `e` as . @@ -740,7 +740,7 @@ ## Examples - The following code example demonstrates the effects of setting the , , and properties. + The following code example demonstrates the effects of setting the , , and properties. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowPensAndSmoothingMode` method when handling the form's event, passing `e` as . @@ -835,17 +835,17 @@ allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ## Examples - The following code example demonstrates the effects of setting the and properties, and shows how to call the method for a . + The following code example demonstrates the effects of setting the and properties, and shows how to call the method for a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -893,7 +893,7 @@ and properties on a . + The following code example demonstrates the effects of setting the and properties on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowStartAndEndCaps` method when handling the form's event, passing `e` as . @@ -985,7 +985,7 @@ ## Examples - The following code example demonstrates the effects of setting the and properties on a . + The following code example demonstrates the effects of setting the and properties on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -1651,7 +1651,7 @@ and properties on a . + The following code example demonstrates the effects of setting the and properties on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowStartAndEndCaps` method when handling the form's event, passing `e` as . @@ -1841,12 +1841,12 @@ object using its property. The unit of measure is typically pixels. A of 0 will result in the drawing as if the were 1. + You can access the unit of measure of the object using its property. The unit of measure is typically pixels. A of 0 will result in the drawing as if the were 1. ## Examples - The following code example demonstrates the effects of setting the and properties on a . + The following code example demonstrates the effects of setting the and properties on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . diff --git a/xml/System.Drawing/Point.xml b/xml/System.Drawing/Point.xml index b47d6699f2f..d7b23b5b277 100644 --- a/xml/System.Drawing/Point.xml +++ b/xml/System.Drawing/Point.xml @@ -81,22 +81,22 @@ Represents an ordered pair of integer x- and y-coordinates that defines a point in a two-dimensional plane. - to a , use . - - - -## Examples - The following code example creates points and sizes using several of the overloaded operators defined for these types. It also demonstrates how to use the class. - - This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . - + to a , use . + + + +## Examples + The following code example creates points and sizes using several of the overloaded operators defined for these types. It also demonstrates how to use the class. + + This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -154,15 +154,15 @@ A that specifies the coordinates for the new . Initializes a new instance of the struct from a . - operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. - + operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: + ]]> @@ -210,20 +210,20 @@ A 32-bit integer that specifies the coordinates for the new . Initializes a new instance of the struct using coordinates specified by an integer value. - . - - - -## Examples - The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1`, and call the `InitializeLabel1` method in the form's constructor. - + . + + + +## Examples + The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1`, and call the `InitializeLabel1` method in the form's constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet7"::: + ]]> @@ -279,15 +279,15 @@ The vertical position of the point. Initializes a new instance of the struct with the specified coordinates. - operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. - + operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: + ]]> @@ -340,19 +340,19 @@ Adds the specified to the specified . The that is the result of the addition operation. - adds the and of the specified to the and values of the specified point. - - - -## Examples - The following example shows how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `AddPoint` method from the event-handling method, passing `e` as . - + adds the and of the specified to the and values of the specified point. + + + +## Examples + The following example shows how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `AddPoint` method from the event-handling method, passing `e` as . + :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet9"::: + ]]> @@ -617,11 +617,11 @@ Returns a hash code for this . An integer value that specifies a hash value for this . - for unique values, as two objects with the same values for their and properties may return the same hash code. This behavior could change in a future release. - + for unique values, as two objects with the same values for their and properties may return the same hash code. This behavior could change in a future release. + ]]> @@ -737,19 +737,19 @@ The used offset this . Translates this by the specified . - and values of this to the sum of the and values of this and `p`. - - - -## Examples - The following example shows how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `OffsetPoint` method from the event-handling method, passing `e` as . - + and values of this to the sum of the and values of this and `p`. + + + +## Examples + The following example shows how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `OffsetPoint` method from the event-handling method, passing `e` as . + :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet10"::: + ]]> @@ -865,17 +865,17 @@ Translates a by a given . The translated . - class. - - This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . - + class. + + This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -930,15 +930,15 @@ if the and values of and are equal; otherwise, . - operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. - + operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: + ]]> @@ -990,17 +990,17 @@ Converts the specified structure to a structure. The that results from the conversion. - class. - - This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . - + class. + + This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -1052,17 +1052,17 @@ Converts the specified structure to a structure. The that results from the conversion. - using overloaded operators. - - This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Be sure that the form contains a named `listBox1`. - + using overloaded operators. + + This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Be sure that the form contains a named `listBox1`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: + ]]> @@ -1180,15 +1180,15 @@ Translates a by the negative of a given . A structure that is translated by the negative of a given structure. - and the operator. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowPointConverter` method when handling the form's event, passing `e` as . - + and the operator. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowPointConverter` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Converters/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ColorConverter/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ColorConverter/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ColorConverter/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -1290,11 +1290,11 @@ Returns the result of subtracting specified from the specified . The that is the result of the subtraction operation. - subtracts the and of the specified from the and values of the specified point. - + subtracts the and of the specified from the and values of the specified point. + ]]> @@ -1459,15 +1459,15 @@ Gets or sets the x-coordinate of this . The x-coordinate of this . - operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. - + operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: + ]]> @@ -1529,15 +1529,15 @@ Gets or sets the y-coordinate of this . The y-coordinate of this . - operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. - + operator and how to construct a from a or two integers. It also demonstrates how to use the and properties. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button1`, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Drawing/PointConverter.xml b/xml/System.Drawing/PointConverter.xml index 878025bb77d..b41cff21e07 100644 --- a/xml/System.Drawing/PointConverter.xml +++ b/xml/System.Drawing/PointConverter.xml @@ -50,20 +50,20 @@ Converts a object from one data type to another. - class is typically used for creating a design-time experience for controls that have properties that are of type , and is used to convert points to strings for display in a designer and to convert strings entered in a designer to a object. Access this class through the object. - - - -## Examples - The following code example demonstrates how to use the and the operator. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowPointConverter` method when handling the form's event, passing `e` as . - + class is typically used for creating a design-time experience for controls that have properties that are of type , and is used to convert points to strings for display in a designer and to convert strings entered in a designer to a object. Access this class through the object. + + + +## Examples + The following code example demonstrates how to use the and the operator. This example is designed to be used with Windows Forms. Paste this code into a form and call the `ShowPointConverter` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Converters/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ColorConverter/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ColorConverter/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ColorConverter/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -218,11 +218,11 @@ if this converter can perform the conversion; otherwise, . - @@ -340,11 +340,11 @@ Converts the specified object to the specified type. The converted object. - method if the object is valid and if the destination type is string. If this method cannot convert to the destination type, this will throw a exception. - + method if the object is valid and if the destination type is string. If this method cannot convert to the destination type, this will throw a exception. + ]]> The conversion cannot be completed. @@ -402,11 +402,11 @@ Creates an instance of this type given a set of property values for the object. The newly created object, or if the object could not be created. The default implementation returns . - is useful for objects that are immutable but still want to provide changeable properties. - + is useful for objects that are immutable but still want to provide changeable properties. + ]]> @@ -523,11 +523,11 @@ Retrieves the set of properties for this type. By default, a type does not return any properties. The set of properties that are exposed for this data type. If no properties are exposed, this method might return . The default implementation always returns . - for the correct data type. - + for the correct data type. + ]]> diff --git a/xml/System.Drawing/PointF.xml b/xml/System.Drawing/PointF.xml index b9cd73b0491..40ee59f7474 100644 --- a/xml/System.Drawing/PointF.xml +++ b/xml/System.Drawing/PointF.xml @@ -76,7 +76,7 @@ to a , use or . + To convert a to a , use or . ]]> @@ -228,7 +228,7 @@ method adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . + The method adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . ]]> @@ -286,12 +286,12 @@ method adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . + The method adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . ## Examples - The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `AddExample`, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste the following code into a Windows Form. Handle the form's event and call `AddExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet6"::: @@ -638,7 +638,7 @@ ## Examples -- The following code example adds a shadow to a using the operator. This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Make sure the form contains a named `listBox1`. +- The following code example adds a shadow to a using the operator. This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Make sure the form contains a named `listBox1`. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet3"::: @@ -705,12 +705,12 @@ operator adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . + The operator adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . - The equivalent method for this operator is + The equivalent method for this operator is ## Examples - The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opAdditionExample`, passing `e` as . + The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opAdditionExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet5"::: @@ -772,7 +772,7 @@ operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opAdditionExample`, passing `e` as . + The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opAdditionExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet5"::: @@ -906,7 +906,7 @@ operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `AddExample`, passing `e` as . + The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `AddExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet6"::: @@ -1039,12 +1039,12 @@ operator subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . + The operator subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . - The equivalent method for this operator is + The equivalent method for this operator is ## Examples - The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opSubtractionExample`, passing `e` as . + The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opSubtractionExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet8"::: @@ -1114,7 +1114,7 @@ method subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . + The method subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . ]]> @@ -1172,12 +1172,12 @@ method subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . + The method subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . ## Examples - The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `SubtractExample`, passing `e` as . + The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `SubtractExample`, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/SetResolution/Form1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/SetResolution/Form1.vb" id="Snippet7"::: diff --git a/xml/System.Drawing/Rectangle.xml b/xml/System.Drawing/Rectangle.xml index 8ba802922dd..460af749904 100644 --- a/xml/System.Drawing/Rectangle.xml +++ b/xml/System.Drawing/Rectangle.xml @@ -84,18 +84,18 @@ , , and upper-left corner represented by the property. + A rectangle is defined by its , , and upper-left corner represented by the property. - To draw rectangles, you need a object and a object. The object provides the method, and the object stores features of the line, such as color and width. The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + To draw rectangles, you need a object and a object. The object provides the method, and the object stores features of the line, such as color and width. The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. - To draw a filled with color, you need a object and an object derived from such as or . The object provides the method and the object provides the color and fill information. + To draw a filled with color, you need a object and an object derived from such as or . The object provides the method and the object provides the color and fill information. For more advanced shapes, use a object. ## Examples - The following example draws a rectangle with its upper-left corner at (10, 10). The rectangle has a width of 100 and a height of 50. The second argument passed to the constructor indicates that the pen width is 5 pixels. + The following example draws a rectangle with its upper-left corner at (10, 10). The rectangle has a width of 100 and a height of 50. The second argument passed to the constructor indicates that the pen width is 5 pixels. When the rectangle is drawn, the pen is centered on the rectangle's boundary. Because the pen width is 5, the sides of the rectangle are drawn 5 pixels wide, such that 1 pixel is drawn on the boundary itself, 2 pixels are drawn on the inside, and 2 pixels are drawn on the outside. For more details on pen alignment, see [How to: Set Pen Width and Alignment](/dotnet/framework/winforms/advanced/how-to-set-pen-width-and-alignment). @@ -227,7 +227,7 @@ , , , and members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + The following code example demonstrates the , , , and members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: @@ -487,7 +487,7 @@ ## Examples - The following code example demonstrates the method and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. + The following code example demonstrates the method and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet3"::: @@ -795,7 +795,7 @@ ## Examples - The following code example demonstrates how to create a rectangle using the method. This example is designed to be used with a Windows Form. Paste this code into a form and call the `CreateARectangleFromLTRB` method when handling the form's event, passing `e` as . + The following code example demonstrates how to create a rectangle using the method. This example is designed to be used with a Windows Form. Paste this code into a form and call the `CreateARectangleFromLTRB` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet7"::: @@ -918,7 +918,7 @@ property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + Changing the property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. ]]> @@ -1200,7 +1200,7 @@ , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + The following code example demonstrates the , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: @@ -1262,7 +1262,7 @@ , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + The following code example demonstrates the , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet1"::: @@ -1329,7 +1329,7 @@ , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + The following code example demonstrates the , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: @@ -1395,7 +1395,7 @@ , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + The following code example demonstrates the , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: @@ -1591,7 +1591,7 @@ ## Examples - The following code example demonstrates the , and methods and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. + The following code example demonstrates the , and methods and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet3"::: @@ -1881,7 +1881,7 @@ and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet5"::: @@ -2116,7 +2116,7 @@ and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet5"::: @@ -2178,12 +2178,12 @@ method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles: A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). + When one of the two rectangles is empty, meaning all of its values are zero, the method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles: A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). ## Examples - The following code example demonstrates how to use the method. This example is designed for use with a Windows Form. Paste this code into a form and call the `ShowRectangleUnion` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the method. This example is designed for use with a Windows Form. Paste this code into a form and call the `ShowRectangleUnion` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet4"::: @@ -2253,7 +2253,7 @@ property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + Changing the property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. ]]> diff --git a/xml/System.Drawing/RectangleConverter.xml b/xml/System.Drawing/RectangleConverter.xml index 49c84328440..1d1fee0f6a4 100644 --- a/xml/System.Drawing/RectangleConverter.xml +++ b/xml/System.Drawing/RectangleConverter.xml @@ -200,11 +200,11 @@ Gets a value indicating whether this converter can convert an object to the given destination type using the context. This method returns if this converter can perform the conversion; otherwise, . - @@ -322,11 +322,11 @@ Converts the specified object to the specified type. The converted object. - method if the object is valid and if the destination type is string. If this method cannot convert to the destination type, it throws a exception. - + method if the object is valid and if the destination type is string. If this method cannot convert to the destination type, it throws a exception. + ]]> The conversion cannot be completed. @@ -497,11 +497,11 @@ Retrieves the set of properties for this type. By default, a type does not return any properties. The set of properties that should be exposed for this data type. If no properties should be exposed, this may return . The default implementation always returns . - method for the correct data type. - + method for the correct data type. + ]]> diff --git a/xml/System.Drawing/RectangleF.xml b/xml/System.Drawing/RectangleF.xml index 15cf78eb9f0..b44ad894a86 100644 --- a/xml/System.Drawing/RectangleF.xml +++ b/xml/System.Drawing/RectangleF.xml @@ -168,7 +168,7 @@ , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet6"::: @@ -236,7 +236,7 @@ , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet5"::: @@ -306,7 +306,7 @@ value represents the y-coordinate of the first point at the bottom edge of the rectangle that is not contained in the rectangle. + The value represents the y-coordinate of the first point at the bottom edge of the rectangle that is not contained in the rectangle. ]]> @@ -1146,7 +1146,7 @@ `e`, an event object. The code creates two objects and draws them to the screen in black and red. Notice that they have to be converted to objects for drawing purposes. Then the code creates a third using the method, converts it to a , and draws it to the screen in blue. Notice the third (blue) rectangle is the area of overlap of the other two rectangles: + This example is designed for use with Windows Forms, and it requires `e`, an event object. The code creates two objects and draws them to the screen in black and red. Notice that they have to be converted to objects for drawing purposes. Then the code creates a third using the method, converts it to a , and draws it to the screen in blue. Notice the third (blue) rectangle is the area of overlap of the other two rectangles: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicRectangleFExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/RectangleF/Inflate/form1.cs" id="Snippet2"::: @@ -1548,7 +1548,7 @@ , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet6"::: @@ -1681,7 +1681,7 @@ ## Examples -The following code example demonstrates how to use the , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . +The following code example demonstrates how to use the , , and members. This example is designed for use with a Windows Form. Paste this code into a form and call the `ConvertRectangleToRectangleF` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet6"::: @@ -1803,7 +1803,7 @@ The following code example demonstrates how to use the value represents the x-coordinate of the first point at the right edge of the rectangle that is not contained in the rectangle. + The value represents the x-coordinate of the first point at the right edge of the rectangle that is not contained in the rectangle. ]]> @@ -2065,12 +2065,12 @@ The following code example demonstrates how to use the method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). + When one of the two rectangles is empty, meaning all of its values are zero, the method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). ## Examples - This example is designed for use with Windows Forms, and it requires e, an event object. The code creates two s and draws them to the screen in black and red. Notice that they have to be converted to s for drawing purposes. Then the code creates a third using the method, converts it to a , and draws it to the screen in blue. Notice the third (blue) rectangle is the smallest possible rectangle that can contain both of the other two rectangles: + This example is designed for use with Windows Forms, and it requires e, an event object. The code creates two s and draws them to the screen in black and red. Notice that they have to be converted to s for drawing purposes. Then the code creates a third using the method, converts it to a , and draws it to the screen in blue. Notice the third (blue) rectangle is the smallest possible rectangle that can contain both of the other two rectangles: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicRectangleFExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/RectangleF/Inflate/form1.cs" id="Snippet3"::: diff --git a/xml/System.Drawing/Region.xml b/xml/System.Drawing/Region.xml index cb0e2aaea8e..83698b5b743 100644 --- a/xml/System.Drawing/Region.xml +++ b/xml/System.Drawing/Region.xml @@ -56,12 +56,12 @@ An application can also use regions in hit-testing operations, such as checking whether a point or a rectangle intersects a region. For more information on using regions for hit-testing, see [How to: Use Hit Testing with a Region](/dotnet/framework/winforms/advanced/how-to-use-hit-testing-with-a-region). - An application can fill a region by using the method and a object. + An application can fill a region by using the method and a object. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code example demonstrates how to use the from one object to set the for another . + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code example demonstrates how to use the from one object to set the for another . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet13"::: @@ -250,7 +250,7 @@ ## Examples - The following code example demonstrates how to use the constructor and method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . + The following code example demonstrates how to use the constructor and method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet7"::: @@ -451,7 +451,7 @@ method. + For an example, see the method. ]]> @@ -620,17 +620,17 @@ allows the resources used by this to be reallocated for other purposes. + Calling allows the resources used by this to be reallocated for other purposes. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ## Examples - The following code example demonstrates the constructor and the and methods. + The following code example demonstrates the constructor and the and methods. This example is designed to be used with Windows Forms. Paste the code into a form and call the `FillRegionExcludingPath` method when handling the form's event, passing `e` as . @@ -741,7 +741,7 @@ constructor and the and methods. + The following code example demonstrates the constructor and the and methods. This example is designed to be used with Windows Forms. Paste the code into a form and call the `FillRegionExcludingPath` method when handling the form's event, passing `e` as . @@ -794,7 +794,7 @@ method. + For a code example, see the method. ]]> @@ -900,7 +900,7 @@ and methods. + For code examples, see the and methods. ]]> @@ -1096,7 +1096,7 @@ method to free the memory used by the GDI region object. + You are responsible for calling the method to free the memory used by the GDI region object. ]]> @@ -1142,12 +1142,12 @@ class allows you to define a custom shape. The shape can be made up of lines, polygons, and curves. describes the shape contained in this . + The class allows you to define a custom shape. The shape can be made up of lines, polygons, and curves. describes the shape contained in this . ## Examples - The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code example demonstrates how to use the from one object to set the for another . + The following code example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. The code example demonstrates how to use the from one object to set the for another . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet13"::: @@ -1246,7 +1246,7 @@ and methods. + For code examples, see the and methods. ]]> @@ -1291,7 +1291,7 @@ method. + For a code example, see the method. ]]> @@ -1397,7 +1397,7 @@ and method`.` + For code examples, see the and method`.` ]]> @@ -1557,7 +1557,7 @@ method. + For a code example, see the method. ]]> @@ -1610,7 +1610,7 @@ method. + For a code example, see the method. ]]> @@ -1662,7 +1662,7 @@ method. + For a code example, see the method. ]]> @@ -1786,7 +1786,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -1841,7 +1841,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -1896,7 +1896,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -1951,7 +1951,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2000,7 +2000,7 @@ method. + For a code example, see the method. ]]> @@ -2057,7 +2057,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2114,7 +2114,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2167,7 +2167,7 @@ method. + For a code example, see the method. ]]> @@ -2220,7 +2220,7 @@ method. + For a code example, see the method. ]]> @@ -2281,7 +2281,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2342,7 +2342,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> @@ -2384,7 +2384,7 @@ constructor and method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . + The following code example demonstrates how to use the constructor and method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet7"::: @@ -2430,7 +2430,7 @@ method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . + The following code example demonstrates how to use the method. This example is designed to be used with Windows Forms. Create a form and paste the following code into it. Call the `FillEmptyRegion` method in the form's event-handling method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet8"::: @@ -2653,7 +2653,7 @@ method. + For a code example, see the method. ]]> @@ -2707,7 +2707,7 @@ and methods. + For a code example, see the and methods. ]]> @@ -2754,7 +2754,7 @@ method. + For a code example, see the method. ]]> @@ -2860,7 +2860,7 @@ and method. + For a code example, see the and method. ]]> @@ -2916,7 +2916,7 @@ and methods. + For a code example, see the and methods. ]]> @@ -2963,7 +2963,7 @@ method. + For a code example, see the method. ]]> @@ -3016,9 +3016,9 @@ - Creates a region using the first rectangle. -- Gets the area for `myRegion` when combined with `complementRect`. +- Gets the area for `myRegion` when combined with `complementRect`. -- Fills the area with blue and draws it to the screen. +- Fills the area with blue and draws it to the screen. Notice that both rectangles are filled with blue, except for the area of overlap. @@ -3069,7 +3069,7 @@ and methods. + For a code example, see the and methods. ]]> diff --git a/xml/System.Drawing/Size.xml b/xml/System.Drawing/Size.xml index 618847c9c8f..58d3ae56518 100644 --- a/xml/System.Drawing/Size.xml +++ b/xml/System.Drawing/Size.xml @@ -85,7 +85,7 @@ ## Remarks -The structure is used to specify a height and width through the property for , , , and other graphics classes. You can perform operations on a by using the overloaded operators such as , , and . The unit for the and of the structure depend on the and settings for the object that is used to draw. +The structure is used to specify a height and width through the property for , , , and other graphics classes. You can perform operations on a by using the overloaded operators such as , , and . The unit for the and of the structure depend on the and settings for the object that is used to draw. ]]> @@ -200,7 +200,7 @@ The structure is used to specify a height and width t and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1` and call the `InitializeLabel1` method in the form's constructor. + The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1` and call the `InitializeLabel1` method in the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet7"::: @@ -261,7 +261,7 @@ The structure is used to specify a height and width t method. To run this example, paste it into a Windows Form. Handle the form's event and call the `AddSizes` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `AddSizes` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet11"::: @@ -534,7 +534,7 @@ The structure is used to specify a height and width t for unique values, as two objects with the same values for their and properties may return the same hash code. This behavior could change in a future release. + You should avoid depending on for unique values, as two objects with the same values for their and properties may return the same hash code. This behavior could change in a future release. ]]> @@ -600,7 +600,7 @@ The structure is used to specify a height and width t and of the structure depend on the and settings for the object that is used to draw. + The unit for the and of the structure depend on the and settings for the object that is used to draw. ]]> @@ -723,7 +723,7 @@ The structure is used to specify a height and width t operator. The example is designed to be used with Windows Forms. To run this example, paste it into a form that contains a button named `addButton` and associate the `addButton_Click` method with the button's event. + The following code example demonstrates the operator. The example is designed to be used with Windows Forms. To run this example, paste it into a form that contains a button named `addButton` and associate the `addButton_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet4"::: @@ -981,7 +981,7 @@ The structure is used to specify a height and width t , , , and properties of a and the member. + The following code example demonstrates the , , , and properties of a and the member. This example is designed to be used with a Windows Form. Paste the code into the form and call the `ShowPropertiesOfSlateBlue` method from the form's event-handling method, passing `e` as . @@ -1277,7 +1277,7 @@ The structure is used to specify a height and width t operator. The example is designed to be used with Windows Forms. To run the example, paste it into a form that contains a button named `subtractionButton` and associate the `subtractButton_Click` method with the button's event. + The following code example demonstrates the operator. The example is designed to be used with Windows Forms. To run the example, paste it into a form that contains a button named `subtractionButton` and associate the `subtractButton_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet2"::: @@ -1337,7 +1337,7 @@ The structure is used to specify a height and width t and methods to convert a to a . This example is designed to be used with Windows Forms. To run this example, paste it into a form that contains two objects named `Label1` and `Label2`, and then call this method from the form's constructor. + The following code example demonstrates how to use static and methods to convert a to a . This example is designed to be used with Windows Forms. To run this example, paste it into a form that contains two objects named `Label1` and `Label2`, and then call this method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet5"::: @@ -1398,7 +1398,7 @@ The structure is used to specify a height and width t method. To run this example, paste it into a Windows Form. Handle the form's event and call the `SubtractSizes` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form's event and call the `SubtractSizes` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet12"::: @@ -1511,7 +1511,7 @@ The structure is used to specify a height and width t and methods to convert a to a . This example is designed to be used with Windows Forms. To run this example, paste it into a form that contains two objects named `Label1` and `Label2`, and then call this method from the form's constructor. + The following code example demonstrates how to use static and methods to convert a to a . This example is designed to be used with Windows Forms. To run this example, paste it into a form that contains two objects named `Label1` and `Label2`, and then call this method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Overview/form1.cs" id="Snippet5"::: @@ -1581,7 +1581,7 @@ The structure is used to specify a height and width t and of the structure depend on the and settings for the object used to draw. + The unit for the and of the structure depend on the and settings for the object used to draw. ]]> diff --git a/xml/System.Drawing/SizeConverter.xml b/xml/System.Drawing/SizeConverter.xml index 8383b2841e6..9cc68069f85 100644 --- a/xml/System.Drawing/SizeConverter.xml +++ b/xml/System.Drawing/SizeConverter.xml @@ -200,11 +200,11 @@ Gets a value indicating whether this converter can convert an object to the given destination type using the context. This method returns if this converter can perform the conversion; otherwise, . - @@ -322,11 +322,11 @@ Converts the specified object to the specified type. The converted object. - method of the object if the object is valid and if the destination type is string. If this method cannot convert the specified object to the destination type, it passes a exception. - + method of the object if the object is valid and if the destination type is string. If this method cannot convert the specified object to the destination type, it passes a exception. + ]]> The conversion cannot be completed. @@ -499,11 +499,11 @@ Retrieves the set of properties for this type. By default, a type does not have any properties to return. The set of properties that should be exposed for this data type. If no properties should be exposed, this may return . The default implementation always returns . - method for the correct data type. - + method for the correct data type. + ]]> diff --git a/xml/System.Drawing/SizeF.xml b/xml/System.Drawing/SizeF.xml index 8d7002b93e4..74846564621 100644 --- a/xml/System.Drawing/SizeF.xml +++ b/xml/System.Drawing/SizeF.xml @@ -81,28 +81,28 @@ Stores an ordered pair of floating-point numbers, typically the width and height of a rectangle. - structure depends on the and settings for the object that is used to draw. - - - -## Examples - The following code example adds a shadow to a by using the following members: - -- - -- - -- - - This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. - + structure depends on the and settings for the object that is used to draw. + + + +## Examples + The following code example adds a shadow to a by using the following members: + +- + +- + +- + + This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: + ]]> @@ -290,23 +290,23 @@ The height component of the new structure. Initializes a new instance of the structure from the specified dimensions. - by using the following members: - -- - -- - -- - - This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. - + by using the following members: + +- + +- + +- + + This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: + ]]> @@ -632,11 +632,11 @@ Gets or sets the vertical component of this structure. The vertical component of this structure, typically measured in pixels. - and of the structure depend on the and settings for the object used to draw. - + and of the structure depend on the and settings for the object used to draw. + ]]> @@ -756,23 +756,23 @@ Adds the width and height of one structure to the width and height of another structure. A structure that is the result of the addition operation. - by using the following members: - -- - -- - -- - - This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. - + by using the following members: + +- + +- + +- + + This example is designed to be used with a Windows Form. To run this example, paste this code into a form and call the `AddShadow` method when handling the form's event. Verify that the form contains a named `listBox1`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form12.vb" id="Snippet3"::: + ]]> @@ -1340,11 +1340,11 @@ Converts a structure to a structure. A structure. - structure is converted to a structure by truncating the values of the to the next lower integer values. - + structure is converted to a structure by truncating the values of the to the next lower integer values. + ]]> @@ -1492,11 +1492,11 @@ Gets or sets the horizontal component of this structure. The horizontal component of this structure, typically measured in pixels. - and of the structure depend on the and settings for the object that is used to draw. - + and of the structure depend on the and settings for the object that is used to draw. + ]]> diff --git a/xml/System.Drawing/StringAlignment.xml b/xml/System.Drawing/StringAlignment.xml index 40e37fd28a4..ff1fff56239 100644 --- a/xml/System.Drawing/StringAlignment.xml +++ b/xml/System.Drawing/StringAlignment.xml @@ -42,7 +42,7 @@ ## Examples - The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet1"::: diff --git a/xml/System.Drawing/StringFormat.xml b/xml/System.Drawing/StringFormat.xml index 271e38ba399..65e1b4cb340 100644 --- a/xml/System.Drawing/StringFormat.xml +++ b/xml/System.Drawing/StringFormat.xml @@ -112,7 +112,7 @@ |Property|Initial Value| |--------------|-------------------| |FormatFlags|0 (no flags are set)| -||| +||| ]]> @@ -156,15 +156,15 @@ ## Examples The following code example demonstrates the following members: -- +- -- +- -- +- -- +- -- +- - @@ -226,15 +226,15 @@ ## Examples The following code example demonstrates the following members: -- +- -- +- -- +- -- +- -- +- - @@ -323,12 +323,12 @@ to specify the vertical alignment of the string. + Use to specify the vertical alignment of the string. ## Examples - The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet1"::: @@ -486,7 +486,7 @@ allows the resources used by this object to be reallocated for other purposes. + Calling allows the resources used by this object to be reallocated for other purposes. ]]> @@ -602,13 +602,13 @@ |Property|Initial Value| |--------------|-------------------| -||0| -||| -||| -||| -||| -||| -||0| +||0| +||| +||| +||| +||| +||| +||0| If you make changes to the object returned from the property, these changes persist, and future calls to the property reflects these changes. @@ -656,13 +656,13 @@ |Property|Initial Value| |--------------|-------------------| -||24580 (, and .)| -||| -||| -||| -||| -||| -||0| +||24580 (, and .)| +||| +||| +||| +||| +||| +||0| ]]> @@ -765,7 +765,7 @@ ## Examples - The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing e as . + The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing e as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet2"::: @@ -811,12 +811,12 @@ to specify the horizontal alignment of the string. + Use to specify the horizontal alignment of the string. ## Examples - The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . + The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet1"::: @@ -937,7 +937,7 @@ - Draws the string and layout rectangle. -- Paints the regions. Each specifies an area that is occupied by a range of characters. The values in the regions are set when the character ranges are measured by the method. +- Paints the regions. Each specifies an area that is occupied by a range of characters. The values in the regions are set when the character ranges are measured by the method. - Repeats the first four steps, but includes trailing spaces in the measurement of each character range. diff --git a/xml/System.Drawing/StringFormatFlags.xml b/xml/System.Drawing/StringFormatFlags.xml index 95a6b76e0ac..8af48c26c30 100644 --- a/xml/System.Drawing/StringFormatFlags.xml +++ b/xml/System.Drawing/StringFormatFlags.xml @@ -40,39 +40,39 @@ Specifies the display and layout information for text strings. - is used by the class. - + is used by the class. + > [!NOTE] -> The FitBlackBox field was misnamed and its behavior is similar to the `NoFitBlackBox` field in the original GDI+ implementation. - - - -## Examples - The following code example demonstrates the following members: - -- - -- - -- - -- - -- - -- - -- - - This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . - +> The FitBlackBox field was misnamed and its behavior is similar to the `NoFitBlackBox` field in the original GDI+ implementation. + + + +## Examples + The following code example demonstrates the following members: + +- + +- + +- + +- + +- + +- + +- + + This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Drawing/SystemBrushes.xml b/xml/System.Drawing/SystemBrushes.xml index 6b297bb17af..198fb7bad34 100644 --- a/xml/System.Drawing/SystemBrushes.xml +++ b/xml/System.Drawing/SystemBrushes.xml @@ -52,7 +52,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing `e` as . + The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet2"::: diff --git a/xml/System.Drawing/SystemColors.xml b/xml/System.Drawing/SystemColors.xml index b5ba922aa22..5f90aefb554 100644 --- a/xml/System.Drawing/SystemColors.xml +++ b/xml/System.Drawing/SystemColors.xml @@ -59,12 +59,12 @@ or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. + Better performance is achieved by using the properties of the or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. ## Examples - The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's `Click` event. + The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's `Click` event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet2"::: diff --git a/xml/System.Drawing/SystemFonts.xml b/xml/System.Drawing/SystemFonts.xml index 89c75a30497..f6ac1c7c564 100644 --- a/xml/System.Drawing/SystemFonts.xml +++ b/xml/System.Drawing/SystemFonts.xml @@ -141,9 +141,9 @@ MS Shell Dlg maps to a font set in the system registry. - If the above fonts are not installed, the default font is Tahoma, 8 point. If Tahoma, 8 point, is not installed, returns the value of the property. + If the above fonts are not installed, the default font is Tahoma, 8 point. If Tahoma, 8 point, is not installed, returns the value of the property. - The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . + The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . ]]> @@ -190,7 +190,7 @@ property returns Tahoma, 8 point. Otherwise, returns the value of the property. The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . + If the operating system is Windows 2000 or Windows XP, the property returns Tahoma, 8 point. Otherwise, returns the value of the property. The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . ]]> @@ -243,7 +243,7 @@ method returns `null` if the specified name does not match a font in the enumeration. + The method returns `null` if the specified name does not match a font in the enumeration. ]]> diff --git a/xml/System.Drawing/SystemIcons.xml b/xml/System.Drawing/SystemIcons.xml index 0e979057a18..c93a9af32cb 100644 --- a/xml/System.Drawing/SystemIcons.xml +++ b/xml/System.Drawing/SystemIcons.xml @@ -52,7 +52,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates how to load a bitmap from an handle, using the enumeration, and the use of the method to draw the rectangle bounds of a bitmap. + The following code example demonstrates how to load a bitmap from an handle, using the enumeration, and the use of the method to draw the rectangle bounds of a bitmap. This example is designed to be used with Windows Forms. Create a form that contains a button named Button2. Paste the code into the form and associate this method with the button's `Click` event. diff --git a/xml/System.Drawing/TextureBrush.xml b/xml/System.Drawing/TextureBrush.xml index 1458df9ad42..b19a869249c 100644 --- a/xml/System.Drawing/TextureBrush.xml +++ b/xml/System.Drawing/TextureBrush.xml @@ -48,7 +48,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a . + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a . This example is designed to be used with Windows Forms. Create a form containing a button named Button2. Paste the code into the form and associate the Button2_Click method with the button's `Click` event. @@ -111,7 +111,7 @@ method. It also demonstrates a . + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates a . This example is designed to be used with Windows Forms. Create a form containing a button named Button2. Paste the code into the form and associate the Button2_Click method with the button's `Click` event. @@ -1176,7 +1176,7 @@ method. It also demonstrates the property and the enumeration. + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates the property and the enumeration. This example is designed to be used with Windows Forms. Create a form containing a button named Button2. Paste the code into the form and associate the Button2_Click method with the button's `Click` event. diff --git a/xml/System.Drawing/ToolboxBitmapAttribute.xml b/xml/System.Drawing/ToolboxBitmapAttribute.xml index df81d749251..557201fd14b 100644 --- a/xml/System.Drawing/ToolboxBitmapAttribute.xml +++ b/xml/System.Drawing/ToolboxBitmapAttribute.xml @@ -46,22 +46,22 @@ Allows you to specify an icon to represent a control in a container, such as the Microsoft Visual Studio Form Designer. - to a control so that containers, such as Microsoft Visual Studio Form Designer, can retrieve an icon that represents the control. The bitmap for the icon can be in a file by itself or embedded in the assembly that contains the control. The size of the bitmap that you embed in the control's assembly (or store in a separate file) should be 16 by 16. The method of a object can return the small 16 by 16 image or a large 32 by 32 image that it creates by scaling the small image. - - If you want to use different versions of your icons with different versions of your assembly, you do not have to modify the for each version. Instead, you can declare the assembly with a or a , and specify a configuration value for each assembly version. In this case, a file name indicated by a is interpreted with the bitmap suffix appended. - - - -## Examples - The following code example demonstrates how to use the class to set `stop.bmp` as the toolbox icon for the `StopSignControl`. This example assumes the existence of a 16-by-16-pixel bitmap named `stop.bmp` at c:\\. - + to a control so that containers, such as Microsoft Visual Studio Form Designer, can retrieve an icon that represents the control. The bitmap for the icon can be in a file by itself or embedded in the assembly that contains the control. The size of the bitmap that you embed in the control's assembly (or store in a separate file) should be 16 by 16. The method of a object can return the small 16 by 16 image or a large 32 by 32 image that it creates by scaling the small image. + + If you want to use different versions of your icons with different versions of your assembly, you do not have to modify the for each version. Instead, you can declare the assembly with a or a , and specify a configuration value for each assembly version. In this case, a file name indicated by a is interpreted with the bitmap suffix appended. + + + +## Examples + The following code example demonstrates how to use the class to set `stop.bmp` as the toolbox icon for the `StopSignControl`. This example assumes the existence of a 16-by-16-pixel bitmap named `stop.bmp` at c:\\. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ToolBoxBitmapExamples/cpp/usercontrol1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet1"::: + ]]> @@ -108,15 +108,15 @@ The name of a file that contains a 16 by 16 bitmap. Initializes a new object with an image from a specified file. - constructor to set `stop.bmp` as the toolbox icon for the `StopSignControl`. This example assumes the existence of a 16-by-16-pixel bitmap named `stop.bmp` at c:\\. - + constructor to set `stop.bmp` as the toolbox icon for the `StopSignControl`. This example assumes the existence of a 16-by-16-pixel bitmap named `stop.bmp` at c:\\. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ToolBoxBitmapExamples/cpp/usercontrol1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet1"::: + ]]> @@ -154,20 +154,20 @@ A whose defining assembly is searched for the bitmap resource. Initializes a new object based on a 16 x 16 bitmap that is embedded as a resource in a specified assembly. - constructor to set the icon of the button control to the toolbox icon for a named `StopSignControl3`. - + constructor to set the icon of the button control to the toolbox icon for a named `StopSignControl3`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ToolBoxBitmapExamples/cpp/usercontrol1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet3"::: + ]]> @@ -207,20 +207,20 @@ The name of the embedded bitmap resource. Initializes a new object based on a 16 by 16 bitmap that is embedded as a resource in a specified assembly. - constructor to set `StopSignControl2.bmp` as a toolbox icon for the `StopSignControl2`. This example assumes the existence of a 16-by-16-pixel bitmap named `StopSignControl2.bmp` with its **BuildAction** property set to **EmbeddedResource**. - + constructor to set `StopSignControl2.bmp` as a toolbox icon for the `StopSignControl2`. This example assumes the existence of a 16-by-16-pixel bitmap named `StopSignControl2.bmp` with its **BuildAction** property set to **EmbeddedResource**. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ToolBoxBitmapExamples/cpp/usercontrol1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet2"::: + ]]> @@ -401,20 +401,20 @@ Gets the small associated with this object. The small associated with this object. - method. - + method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ToolBoxBitmapExamples/cpp/usercontrol1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/ToolboxBitmapAttribute/Overview/usercontrol1.vb" id="Snippet4"::: + ]]> @@ -469,11 +469,11 @@ Gets the small associated with this object. The small associated with this object. - @@ -518,13 +518,13 @@ Gets the small or large associated with this object. An object associated with this object. - object does not already have a large image, this method creates a large image by scaling the small image. - + object does not already have a large image, this method creates a large image by scaling the small image. + ]]> @@ -581,13 +581,13 @@ Gets the small or large associated with this object. An associated with this object. - object does not already have a large image, this method creates a large image by scaling the small image. - + object does not already have a large image, this method creates a large image by scaling the small image. + ]]> @@ -641,13 +641,13 @@ Gets the small or large associated with this object. An associated with this object. - object does not already have a large image, this method creates a large image by scaling the small image. - + object does not already have a large image, this method creates a large image by scaling the small image. + ]]> @@ -701,13 +701,13 @@ Returns an object based on a bitmap resource that is embedded in an assembly. An object based on the retrieved bitmap. - diff --git a/xml/System.Dynamic/DynamicMetaObject.xml b/xml/System.Dynamic/DynamicMetaObject.xml index 2e7b570ae41..8ec3a348575 100644 --- a/xml/System.Dynamic/DynamicMetaObject.xml +++ b/xml/System.Dynamic/DynamicMetaObject.xml @@ -65,11 +65,11 @@ Represents the dynamic binding and a binding logic of an object participating in the dynamic binding. - @@ -273,11 +273,11 @@ Performs the binding of the dynamic conversion operation. The new representing the result of the binding. - or functions. - + or functions. + ]]> @@ -1060,11 +1060,11 @@ if runtime value is available, a type of the otherwise. - . - + . + ]]> diff --git a/xml/System.Dynamic/DynamicObject.xml b/xml/System.Dynamic/DynamicObject.xml index e823f015094..70a3774b1fd 100644 --- a/xml/System.Dynamic/DynamicObject.xml +++ b/xml/System.Dynamic/DynamicObject.xml @@ -78,56 +78,56 @@ Provides a base class for specifying dynamic behavior at run time. This class must be inherited from; you cannot instantiate it directly. - and methods. - - In C#, to enable dynamic behavior for instances of classes derived from the `DynamicObject` class, you must use the `dynamic` keyword. For more information, see [Using Type dynamic](/dotnet/csharp/programming-guide/types/using-type-dynamic). - - In Visual Basic, dynamic operations are supported by late binding. For more information, see [Early and Late Binding (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/early-late-binding/). - - The following code example demonstrates how to create an instance of a class that is derived from the `DynamicObject` class. - -```csharp -public class SampleDynamicObject : DynamicObject {} -//... -dynamic sampleObject = new SampleDynamicObject (); -``` - -```vb -Public Class SampleDynamicObject - Inherits DynamicObject -'... -Dim sampleObject As Object = New SampleDynamicObject() -``` - - You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. - - The `DynamicObject` class implements the DLR interface , which enables you to share instances of the `DynamicObject` class between languages that support the DLR interoperability model. For example, you can create an instance of the `DynamicObject` class in C# and then pass it to an IronPython function. For more information, see [Dynamic Language Runtime Overview](/dotnet/framework/reflection-and-codedom/dynamic-language-runtime-overview). - + and methods. + + In C#, to enable dynamic behavior for instances of classes derived from the `DynamicObject` class, you must use the `dynamic` keyword. For more information, see [Using Type dynamic](/dotnet/csharp/programming-guide/types/using-type-dynamic). + + In Visual Basic, dynamic operations are supported by late binding. For more information, see [Early and Late Binding (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/early-late-binding/). + + The following code example demonstrates how to create an instance of a class that is derived from the `DynamicObject` class. + +```csharp +public class SampleDynamicObject : DynamicObject {} +//... +dynamic sampleObject = new SampleDynamicObject (); +``` + +```vb +Public Class SampleDynamicObject + Inherits DynamicObject +'... +Dim sampleObject As Object = New SampleDynamicObject() +``` + + You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. + + The `DynamicObject` class implements the DLR interface , which enables you to share instances of the `DynamicObject` class between languages that support the DLR interoperability model. For example, you can create an instance of the `DynamicObject` class in C# and then pass it to an IronPython function. For more information, see [Dynamic Language Runtime Overview](/dotnet/framework/reflection-and-codedom/dynamic-language-runtime-overview). + > [!NOTE] -> If you have a simple scenario in which you need an object that can only add and remove members at run time but that does not need to define specific operations and does not have static members, use the class. -> -> If you have a more advanced scenario in which you need to define how dynamic objects participate in the interoperability protocol, or you need to manage DLR fast dynamic dispatch caching, create your own implementation of the interface. - - - -## Examples - Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, you want this syntax to be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. - - The following code example demonstrates the `DynamicDictionary` class, which is derived from the `DynamicObject` class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. - +> If you have a simple scenario in which you need an object that can only add and remove members at run time but that does not need to define specific operations and does not have static members, use the class. +> +> If you have a more advanced scenario in which you need to define how dynamic objects participate in the interoperability protocol, or you need to manage DLR fast dynamic dispatch caching, create your own implementation of the interface. + + + +## Examples + Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, you want this syntax to be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. + + The following code example demonstrates the `DynamicDictionary` class, which is derived from the `DynamicObject` class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: - - For more examples, see [Creating Wrappers with DynamicObject](https://devblogs.microsoft.com/csharpfaq/dynamic-in-c-4-0-creating-wrappers-with-dynamicobject/) on the C# Frequently Asked Questions blog. - - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: + + For more examples, see [Creating Wrappers with DynamicObject](https://devblogs.microsoft.com/csharpfaq/dynamic-in-c-4-0-creating-wrappers-with-dynamicobject/) on the C# Frequently Asked Questions blog. + + ]]> @@ -176,33 +176,33 @@ Dim sampleObject As Object = New SampleDynamicObject() Enables derived types to initialize a new instance of the type. - class. To implement dynamic behavior, you have to inherit from the class and override necessary methods. - - In C#, to enable dynamic behavior for instances of the classes derived from the class, you must use the `dynamic` keyword. For more information, see [Using Type dynamic](/dotnet/csharp/programming-guide/types/using-type-dynamic). - - In Visual Basic, dynamic operations are supported by late binding. For more information, see [Early and Late Binding (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/early-late-binding/). - - - -## Examples - The following code example demonstrates how to create an instance of classes that are derived from the class. - -```csharp -public class SampleDynamicObject : DynamicObject {} -//... -dynamic sampleObject = new SampleDynamicObject (); -``` - -```vb -Public Class SampleDynamicObject - Inherits DynamicObject -'... -Dim sampleObject As Object = New SampleDynamicObject() -``` - + class. To implement dynamic behavior, you have to inherit from the class and override necessary methods. + + In C#, to enable dynamic behavior for instances of the classes derived from the class, you must use the `dynamic` keyword. For more information, see [Using Type dynamic](/dotnet/csharp/programming-guide/types/using-type-dynamic). + + In Visual Basic, dynamic operations are supported by late binding. For more information, see [Early and Late Binding (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/early-late-binding/). + + + +## Examples + The following code example demonstrates how to create an instance of classes that are derived from the class. + +```csharp +public class SampleDynamicObject : DynamicObject {} +//... +dynamic sampleObject = new SampleDynamicObject (); +``` + +```vb +Public Class SampleDynamicObject + Inherits DynamicObject +'... +Dim sampleObject As Object = New SampleDynamicObject() +``` + ]]> @@ -250,11 +250,11 @@ Dim sampleObject As Object = New SampleDynamicObject() Returns the enumeration of all dynamic member names. A sequence that contains dynamic member names. - @@ -369,65 +369,65 @@ Dim sampleObject As Object = New SampleDynamicObject() if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how binary operations should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - This method is called when you have binary operations such as addition or multiplication. For example, if the method is overridden, it is automatically invoked for statements like `sum = first + second` or `multiply = first*second`, where `first` is derived from the `DynamicObject` class. - - You can get information about the type of the binary operation by using the `Operation` property of the `binder` parameter. - + class can override this method to specify how binary operations should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + This method is called when you have binary operations such as addition or multiplication. For example, if the method is overridden, it is automatically invoked for statements like `sum = first + second` or `multiply = first*second`, where `first` is derived from the `DynamicObject` class. + + You can get information about the type of the binary operation by using the `Operation` property of the `binder` parameter. + If your dynamic object is used only in C# and Visual Basic, the `binder.Operation` property can have one of the following values from the enumeration. However, in other languages such as IronPython or IronRuby, you can have other values. - -|Value|Description|C#|Visual Basic| -|-----------|-----------------|---------|------------------| -|`Add`|An addition operation without overflow checking, for numeric operands.|`a + b`|`a + b`| -|`AddAssign`|An addition compound assignment operation without overflow checking, for numeric operands.|`a += b`|Not supported.| -|`And`|A bitwise `AND` operation.|`a & b`|`a And b`| -|`AndAssign`|A bitwise `AND` compound assignment operation.|`a &= b`|Not supported.| -|`Divide`|An arithmetic division operation.|`a / b`|`a / b`| -|`DivideAssign`|An arithmetic division compound assignment operation.|`a /= b`|Not supported.| -|`ExclusiveOr`|A bitwise `XOR` operation.|`a ^ b`|`a Xor b`| -|`ExclusiveOrAssign`|A bitwise `XOR` compound assignment operation.|`a ^= b`|Not supported.| -|`GreaterThan`|A "greater than" comparison.|`a > b`|`a > b`| -|`GreaterThanOrEqual`|A "greater than or equal to" comparison.|`a >= b`|Not supported.| -|`LeftShift`|A bitwise left-shift operation.|`a << b`|`a << b`| -|`LeftShiftAssign`|A bitwise left-shift compound assignment operation.|`a <<= b`|Not supported.| -|`LessThan`|A "less than" comparison.|`a < b`|`a < b`| -|`LessThanOrEqual`|A "less than or equal to" comparison.|`a <= b`|Not supported.| -|`Modulo`|An arithmetic remainder operation.|`a % b`|`a Mod b`| -|`ModuloAssign`|An arithmetic remainder compound assignment operation.|`a %= b`|Not supported.| -|`Multiply`|A multiplication operation without overflow checking, for numeric operands.|`a * b`|`a * b`| -|`MultiplyAssign`|A multiplication compound assignment operation without overflow checking, for numeric operands.|`a *= b`|Not supported.| -|`NotEqual`|An inequality comparison.|`a != b`|`a <> b`| -|`Or`|A bitwise or logical `OR` operation.|`a | b`|`a Or b`| -|`OrAssign`|A bitwise or logical `OR` compound assignment.|`a |= b`|Not supported.| -|`Power`|A mathematical operation of raising a number to a power.|Not supported.|`a ^ b`| -|`RightShift`|A bitwise right-shift operation.|`a >> b`|`a >> b`| -|`RightShiftAssign`|A bitwise right-shift compound assignment operation.|`a >>= b`|Not supported.| -|`Subtract`|A subtraction operation without overflow checking, for numeric operands.|`a - b`|`a - b`| -|`SubtractAssign`|A subtraction compound assignment operation without overflow checking, for numeric operands.|`a -= b`|Not supported.| - + +|Value|Description|C#|Visual Basic| +|-----------|-----------------|---------|------------------| +|`Add`|An addition operation without overflow checking, for numeric operands.|`a + b`|`a + b`| +|`AddAssign`|An addition compound assignment operation without overflow checking, for numeric operands.|`a += b`|Not supported.| +|`And`|A bitwise `AND` operation.|`a & b`|`a And b`| +|`AndAssign`|A bitwise `AND` compound assignment operation.|`a &= b`|Not supported.| +|`Divide`|An arithmetic division operation.|`a / b`|`a / b`| +|`DivideAssign`|An arithmetic division compound assignment operation.|`a /= b`|Not supported.| +|`ExclusiveOr`|A bitwise `XOR` operation.|`a ^ b`|`a Xor b`| +|`ExclusiveOrAssign`|A bitwise `XOR` compound assignment operation.|`a ^= b`|Not supported.| +|`GreaterThan`|A "greater than" comparison.|`a > b`|`a > b`| +|`GreaterThanOrEqual`|A "greater than or equal to" comparison.|`a >= b`|Not supported.| +|`LeftShift`|A bitwise left-shift operation.|`a << b`|`a << b`| +|`LeftShiftAssign`|A bitwise left-shift compound assignment operation.|`a <<= b`|Not supported.| +|`LessThan`|A "less than" comparison.|`a < b`|`a < b`| +|`LessThanOrEqual`|A "less than or equal to" comparison.|`a <= b`|Not supported.| +|`Modulo`|An arithmetic remainder operation.|`a % b`|`a Mod b`| +|`ModuloAssign`|An arithmetic remainder compound assignment operation.|`a %= b`|Not supported.| +|`Multiply`|A multiplication operation without overflow checking, for numeric operands.|`a * b`|`a * b`| +|`MultiplyAssign`|A multiplication compound assignment operation without overflow checking, for numeric operands.|`a *= b`|Not supported.| +|`NotEqual`|An inequality comparison.|`a != b`|`a <> b`| +|`Or`|A bitwise or logical `OR` operation.|`a | b`|`a Or b`| +|`OrAssign`|A bitwise or logical `OR` compound assignment.|`a |= b`|Not supported.| +|`Power`|A mathematical operation of raising a number to a power.|Not supported.|`a ^ b`| +|`RightShift`|A bitwise right-shift operation.|`a >> b`|`a >> b`| +|`RightShiftAssign`|A bitwise right-shift compound assignment operation.|`a >>= b`|Not supported.| +|`Subtract`|A subtraction operation without overflow checking, for numeric operands.|`a - b`|`a - b`| +|`SubtractAssign`|A subtraction compound assignment operation without overflow checking, for numeric operands.|`a -= b`|Not supported.| + > [!NOTE] -> To implement `OrElse` (`a || b`) and `AndAlso` (`a && b`) operations for dynamic objects in C#, you may want to implement both the method and the method. -> -> The `OrElse` operation consists of the unary `IsTrue` operation and the binary `Or` operation. The `Or` operation is performed only if the result of the `IsTrue` operation is `false`. -> -> The `AndAlso` operation consists of the unary `IsFalse` operation and the binary `And` operation. The `And` operation is performed only if the result of the `IsFalse` operation is `false`. - - - -## Examples - Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define basic mathematical operations such as addition and subtraction for such data. - - The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable mathematical operations. It also overrides the and methods to enable access to the elements. - - In this example, only addition and subtraction operations are supported. If you try to write a statement like `resultNumber = firstNumber*secondNumber`, a run-time exception is thrown. - +> To implement `OrElse` (`a || b`) and `AndAlso` (`a && b`) operations for dynamic objects in C#, you may want to implement both the method and the method. +> +> The `OrElse` operation consists of the unary `IsTrue` operation and the binary `Or` operation. The `Or` operation is performed only if the result of the `IsTrue` operation is `false`. +> +> The `AndAlso` operation consists of the unary `IsFalse` operation and the binary `And` operation. The `And` operation is performed only if the result of the `IsFalse` operation is `false`. + + + +## Examples + Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define basic mathematical operations such as addition and subtraction for such data. + + The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable mathematical operations. It also overrides the and methods to enable access to the elements. + + In this example, only addition and subtraction operations are supported. If you try to write a statement like `resultNumber = firstNumber*secondNumber`, a run-time exception is thrown. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet2"::: + ]]> @@ -489,41 +489,41 @@ Dim sampleObject As Object = New SampleDynamicObject() if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how a type conversion should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - In C#, if this method is overridden, it is automatically invoked when you have an explicit or implicit conversion, as shown in the code example below. - - In Visual Basic, only explicit conversion is supported. If you override this method, you call it by using the or functions. - -```csharp -// Explicit conversion. -String sampleExplicit = (String)sampleObject; -// Implicit conversion. -String sampleImplicit = sampleObject; -``` - -```vb -// Explicit conversion - first variant. -Dim testExplicit1 = CTypeDynamic(Of String)(sampleObject) -// Explicit conversion - second variant. -Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) -``` - - - -## Examples - Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define conversions of this data structure to strings and integers. - - The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable type conversion. It also overrides the and methods to enable access to the data elements. - - In this example, only conversion to strings and integers is supported. If you try to convert an object to any other type, a run-time exception is thrown. - + class can override this method to specify how a type conversion should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + In C#, if this method is overridden, it is automatically invoked when you have an explicit or implicit conversion, as shown in the code example below. + + In Visual Basic, only explicit conversion is supported. If you override this method, you call it by using the or functions. + +```csharp +// Explicit conversion. +String sampleExplicit = (String)sampleObject; +// Implicit conversion. +String sampleImplicit = sampleObject; +``` + +```vb +// Explicit conversion - first variant. +Dim testExplicit1 = CTypeDynamic(Of String)(sampleObject) +// Explicit conversion - second variant. +Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) +``` + + + +## Examples + Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define conversions of this data structure to strings and integers. + + The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable type conversion. It also overrides the and methods to enable access to the data elements. + + In this example, only conversion to strings and integers is supported. If you try to convert an object to any other type, a run-time exception is thrown. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet3"::: + ]]> @@ -594,13 +594,13 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how a new instance of the dynamic object should be initialized. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - C# and Visual Basic compilers never emit code to use this method because they do not support first-class types. This method is intended for languages that support the initialization of dynamic objects by using syntax like `dynamic new`. - + class can override this method to specify how a new instance of the dynamic object should be initialized. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + C# and Visual Basic compilers never emit code to use this method because they do not support first-class types. This method is intended for languages that support the initialization of dynamic objects by using syntax like `dynamic new`. + ]]> @@ -654,13 +654,13 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how a value that has a specified index should be deleted. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - C# and Visual Basic compilers never emit code to use this method because they do not support this kind of operation. This method is intended for languages that support syntax for deleting objects by index, such as `del sampleObject[1,2]` in Python. - + class can override this method to specify how a value that has a specified index should be deleted. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + C# and Visual Basic compilers never emit code to use this method because they do not support this kind of operation. This method is intended for languages that support syntax for deleting objects by index, such as `del sampleObject[1,2]` in Python. + ]]> @@ -712,13 +712,13 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how an object member should be deleted. When this method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - C# and Visual Basic compilers never emit code to use this method because they do not support this kind of operation. This method is intended for languages that support syntax for deleting members, such as `del sampleObject.SampleMember` in Python. - + class can override this method to specify how an object member should be deleted. When this method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + C# and Visual Basic compilers never emit code to use this method because they do not support this kind of operation. This method is intended for languages that support syntax for deleting members, such as `del sampleObject.SampleMember` in Python. + ]]> @@ -782,23 +782,23 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) - class can override this method to specify how getting a value by index should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) - - If this method is overridden, it is automatically invoked when you have an operation like `sampleObject[3]` in C# or `sampleObject(3)` in Visual Basic, where `sampleObject` is derived from the class. - - - -## Examples - Assume that you want to create an object in which properties can be accessed either by names such as `Property0`, `Property1`, and so on, or by index, so that, for example, `sampleObject.Property0` is equivalent to `sampleObject[0]` in C# or `sampleObject(0)` in Visual Basic. - - The following code example demonstrates the `SampleDynamicObject` class, which is derived from the class. The `SampleDynamicObject` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. `SampleDynamicObject` overrides the and methods to enable access by index. It overrides the and methods to enable access by property name. - + class can override this method to specify how getting a value by index should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) + + If this method is overridden, it is automatically invoked when you have an operation like `sampleObject[3]` in C# or `sampleObject(3)` in Visual Basic, where `sampleObject` is derived from the class. + + + +## Examples + Assume that you want to create an object in which properties can be accessed either by names such as `Property0`, `Property1`, and so on, or by index, so that, for example, `sampleObject.Property0` is equivalent to `sampleObject[0]` in C# or `sampleObject(0)` in Visual Basic. + + The following code example demonstrates the `SampleDynamicObject` class, which is derived from the class. The `SampleDynamicObject` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. `SampleDynamicObject` overrides the and methods to enable access by index. It overrides the and methods to enable access by property name. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet4"::: + ]]> @@ -860,25 +860,25 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) - class can override this method to specify how operations that get member values should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) - - This method is called when you have statements like `Console.WriteLine(sampleObject.SampleProperty)`, where `sampleObject` is an instance of the class derived from the class. - - You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. - - - -## Examples - Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, this syntax must be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. - - The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. - + class can override this method to specify how operations that get member values should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) + + This method is called when you have statements like `Console.WriteLine(sampleObject.SampleProperty)`, where `sampleObject` is an instance of the class derived from the class. + + You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. + + + +## Examples + Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, this syntax must be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. + + The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: + ]]> @@ -942,24 +942,24 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown. - class can override this method to specify how operations that invoke an object should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) - - If this method is overridden, it is automatically invoked when you have an operation like `sampleObject(100)`, where `sampleObject` is derived from the class. - - The operation for invoking an object is supported in C# but not in Visual Basic. The Visual Basic compiler never emits code to use this method, and the Visual Basic language does not support syntax like `sampleObject(100)`. - - - -## Examples - Assume that you need a data structure to store textual and numeric representations of numbers. You want to be able to specify the value for each property individually and also to be able to initialize all properties in a single statement. - - The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable initialization of all properties at one time. It also overrides the and methods to enable access to individual object properties. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet5"::: - + class can override this method to specify how operations that invoke an object should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a run-time exception is thrown.) + + If this method is overridden, it is automatically invoked when you have an operation like `sampleObject(100)`, where `sampleObject` is derived from the class. + + The operation for invoking an object is supported in C# but not in Visual Basic. The Visual Basic compiler never emits code to use this method, and the Visual Basic language does not support syntax like `sampleObject(100)`. + + + +## Examples + Assume that you need a data structure to store textual and numeric representations of numbers. You want to be able to specify the value for each property individually and also to be able to initialize all properties in a single statement. + + The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable initialization of all properties at one time. It also overrides the and methods to enable access to individual object properties. + + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet5"::: + ]]> @@ -1023,27 +1023,27 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how operations that invoke an object member should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - If this method is overridden, it is automatically invoked when you perform an operation like `sampleObject.SampleMethod(100)`, where `sampleObject` is derived from the `DynamicObject` class. - - You can also add your own methods to classes that are derived from the class. For example, if you override the method, the dynamic dispatch system first attempts to determine whether the specified method exists in the class. If it does not find the method, it uses the implementation. - - This method does not support `ref` and `out` parameters. All parameters in the `args` array are passed by value. - - - -## Examples - Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, you want to be able to call all the standard dictionary methods on this dictionary. - - The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. It overrides the method to support methods of the class and overrides the and methods to support the new syntax. It also provides a `Print` method, which prints out all dictionary keys and values. - + class can override this method to specify how operations that invoke an object member should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + If this method is overridden, it is automatically invoked when you perform an operation like `sampleObject.SampleMethod(100)`, where `sampleObject` is derived from the `DynamicObject` class. + + You can also add your own methods to classes that are derived from the class. For example, if you override the method, the dynamic dispatch system first attempts to determine whether the specified method exists in the class. If it does not find the method, it uses the implementation. + + This method does not support `ref` and `out` parameters. All parameters in the `args` array are passed by value. + + + +## Examples + Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, you want to be able to call all the standard dictionary methods on this dictionary. + + The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. It overrides the method to support methods of the class and overrides the and methods to support the new syntax. It also provides a `Print` method, which prints out all dictionary keys and values. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet6"::: + ]]> @@ -1107,23 +1107,23 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown. - class can override this method to specify how operations that access an object by index should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - If this method is overridden, it is automatically invoked when you have an operation like `sampleObject[3] = 10` in C# or `sampleObject(3) = 10` in Visual Basic, where `sampleObject` is derived from the class. - - - -## Examples - Assume that you want to create an object in which properties can be accessed either by names such as `Property0`, `Property1`, and so on, or by index, so that, for example, `sampleObject.Property0` is equivalent to `sampleObject[0]` in C# or `sampleObject(0)` in Visual Basic. - - The following code example demonstrates the `SampleDynamicObject` class, which is derived from the class. The `SampleDynamicObject` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. `SampleDynamicObject` overrides the and methods to enable access by index. It overrides the and methods to enable access by property name. - + class can override this method to specify how operations that access an object by index should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + If this method is overridden, it is automatically invoked when you have an operation like `sampleObject[3] = 10` in C# or `sampleObject(3) = 10` in Visual Basic, where `sampleObject` is derived from the class. + + + +## Examples + Assume that you want to create an object in which properties can be accessed either by names such as `Property0`, `Property1`, and so on, or by index, so that, for example, `sampleObject.Property0` is equivalent to `sampleObject[0]` in C# or `sampleObject(0)` in Visual Basic. + + The following code example demonstrates the `SampleDynamicObject` class, which is derived from the class. The `SampleDynamicObject` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs. `SampleDynamicObject` overrides the and methods to enable access by index. It overrides the and methods to enable access by property name. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet4"::: + ]]> @@ -1185,25 +1185,25 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how operations that set a value to a member should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - This method is called when you have statements like `sampleObject.SampleProperty = "Test"`, where `sampleObject` is an instance of the class that is derived from the class. - - You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. - - - -## Examples - Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, this syntax must be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. - - The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. - + class can override this method to specify how operations that set a value to a member should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + This method is called when you have statements like `sampleObject.SampleProperty = "Test"`, where `sampleObject` is an instance of the class that is derived from the class. + + You can also add your own members to classes derived from the `DynamicObject` class. If your class defines properties and also overrides the method, the dynamic language runtime (DLR) first uses the language binder to look for a static definition of a property in the class. If there is no such property, the DLR calls the method. + + + +## Examples + Assume that you want to provide alternative syntax for accessing values in a dictionary, so that instead of writing `sampleDictionary["Text"] = "Sample text"` (`sampleDictionary("Text") = "Sample text"` in Visual Basic), you can write `sampleDictionary.Text = "Sample text"`. Also, this syntax must be case-insensitive, so that `sampleDictionary.Text` is equivalent to `sampleDictionary.text`. + + The following code example demonstrates the `DynamicDictionary` class, which is derived from the class. The `DynamicDictionary` class contains an object of the `Dictionary` type (`Dictionary(Of String, Object)` in Visual Basic) to store the key-value pairs, and overrides the and methods to support the new syntax. It also provides a `Count` property, which shows how many dynamic properties the dictionary contains. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet1"::: + ]]> @@ -1265,47 +1265,47 @@ Dim testExplicit2 = CTypeDynamic(sampleObject, GetType(String)) if the operation is successful; otherwise, . If this method returns , the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - class can override this method to specify how unary operations should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) - - This method is called when you have unary operations such as negation, increment, or decrement. For example, if the method is overridden, this method is automatically invoked for statements like `negativeNumber = -number`, where `number` is derived from the class. - - You can get information about the type of the unary operation by using the `Operation` property of the `binder` parameter. - + class can override this method to specify how unary operations should be performed for a dynamic object. When the method is not overridden, the run-time binder of the language determines the behavior. (In most cases, a language-specific run-time exception is thrown.) + + This method is called when you have unary operations such as negation, increment, or decrement. For example, if the method is overridden, this method is automatically invoked for statements like `negativeNumber = -number`, where `number` is derived from the class. + + You can get information about the type of the unary operation by using the `Operation` property of the `binder` parameter. + If your dynamic object is used only in C# and Visual Basic, the `binder.Operation` property can have one of the following values from the enumeration. However, in other languages such as IronPython or IronRuby, you can have other values. - -|Value|Description|C#|Visual Basic| -|-----------|-----------------|---------|------------------| -|`Decrement`|A unary decrement operation.|`a--`|Not supported.| -|`Increment`|A unary increment operation.|`a++`|Not supported.| -|`Negate`|An arithmetic negation.|`-a`|`-a`| -|`Not`|A logical negation.|`!a`|`Not a`| -|`OnesComplement`|A ones complement.|`~a`|Not supported.| -|`IsFalse`|A false condition value.|`a && b`|Not supported.| -|`IsTrue`|A true condition value.|`a || b`|Not supported.| -|`UnaryPlus`|A unary plus.|`+a`|`+a`| - + +|Value|Description|C#|Visual Basic| +|-----------|-----------------|---------|------------------| +|`Decrement`|A unary decrement operation.|`a--`|Not supported.| +|`Increment`|A unary increment operation.|`a++`|Not supported.| +|`Negate`|An arithmetic negation.|`-a`|`-a`| +|`Not`|A logical negation.|`!a`|`Not a`| +|`OnesComplement`|A ones complement.|`~a`|Not supported.| +|`IsFalse`|A false condition value.|`a && b`|Not supported.| +|`IsTrue`|A true condition value.|`a || b`|Not supported.| +|`UnaryPlus`|A unary plus.|`+a`|`+a`| + > [!NOTE] -> To implement `OrElse` (`a || b`) and `AndAlso` (`a && b`) operations for dynamic objects in C#, you may want to implement both the method and the method. -> -> The `OrElse` operation consists of the unary `IsTrue` operation and the binary `Or` operation. The `Or` operation is performed only if the result of the `IsTrue` operation is `false`. -> -> The `AndAlso` operation consists of the unary `IsFalse` operation and the binary `And` operation. The `And` operation is performed only if the result of the `IsFalse` operation is `false`. - - - -## Examples - Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define a mathematical negation operation for such data. - - The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable the mathematical negation operation. Is also overrides the and methods to enable access to the elements. - - In this example, only the mathematical negation operation is supported. If you try to write a statement like `negativeNumber = +number`, a run-time exception occurs. - +> To implement `OrElse` (`a || b`) and `AndAlso` (`a && b`) operations for dynamic objects in C#, you may want to implement both the method and the method. +> +> The `OrElse` operation consists of the unary `IsTrue` operation and the binary `Or` operation. The `Or` operation is performed only if the result of the `IsTrue` operation is `false`. +> +> The `AndAlso` operation consists of the unary `IsFalse` operation and the binary `And` operation. The `And` operation is performed only if the result of the `IsFalse` operation is `false`. + + + +## Examples + Assume that you need a data structure to store textual and numeric representations of numbers, and you want to define a mathematical negation operation for such data. + + The following code example demonstrates the `DynamicNumber` class, which is derived from the class. `DynamicNumber` overrides the method to enable the mathematical negation operation. Is also overrides the and methods to enable access to the elements. + + In this example, only the mathematical negation operation is supported. If you try to write a statement like `negativeNumber = +number`, a run-time exception occurs. + :::code language="csharp" source="~/snippets/csharp/System.Dynamic/DynamicObject/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Dynamic/DynamicObject/Overview/module1.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Dynamic/IDynamicMetaObjectProvider.xml b/xml/System.Dynamic/IDynamicMetaObjectProvider.xml index bbcb3fec247..202fbee26d8 100644 --- a/xml/System.Dynamic/IDynamicMetaObjectProvider.xml +++ b/xml/System.Dynamic/IDynamicMetaObjectProvider.xml @@ -57,13 +57,13 @@ Represents a dynamic object, that can have its operations bound at runtime. - to return a . - - For more information, download the [Implementing Dynamic Interfaces](https://download.microsoft.com/download/5/4/B/54B83DFE-D7AA-4155-9687-B0CF58FF65D7/implementing-dynamic-interfaces.pdf) article available in PDF format. - + to return a . + + For more information, download the [Implementing Dynamic Interfaces](https://download.microsoft.com/download/5/4/B/54B83DFE-D7AA-4155-9687-B0CF58FF65D7/implementing-dynamic-interfaces.pdf) article available in PDF format. + ]]> From 196b5f88dc256bd330acd3f203f843d8b9d89ccd Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:21:04 -0700 Subject: [PATCH 2/2] more unencodings --- xml/System.Data.Objects/ObjectQuery`1.xml | 2 +- xml/System.Data.Objects/ObjectResult`1.xml | 2 +- .../DataServiceCollection`1.xml | 2 +- .../EventSource.xml | 2 +- xml/System.Diagnostics/Debug.xml | 2 +- .../DelimitedListTraceListener.xml | 2 +- .../EventSchemaTraceListener.xml | 2 +- xml/System.Diagnostics/TraceSource.xml | 4 +-- .../XmlWriterTraceListener.xml | 2 +- xml/System.Drawing.Drawing2D/GraphicsPath.xml | 30 +++++++++---------- xml/System.Drawing.Drawing2D/Matrix.xml | 4 +-- .../ImageAttributes.xml | 2 +- xml/System.Drawing/Graphics.xml | 6 ++-- 13 files changed, 31 insertions(+), 31 deletions(-) diff --git a/xml/System.Data.Objects/ObjectQuery`1.xml b/xml/System.Data.Objects/ObjectQuery`1.xml index a420a30acd4..4e878fb3db8 100644 --- a/xml/System.Data.Objects/ObjectQuery`1.xml +++ b/xml/System.Data.Objects/ObjectQuery`1.xml @@ -799,7 +799,7 @@ The method can only be applied executes the query. + Calling executes the query. ]]> diff --git a/xml/System.Data.Objects/ObjectResult`1.xml b/xml/System.Data.Objects/ObjectResult`1.xml index 324a49dc47c..86750572886 100644 --- a/xml/System.Data.Objects/ObjectResult`1.xml +++ b/xml/System.Data.Objects/ObjectResult`1.xml @@ -31,7 +31,7 @@ and . Instances of this class are returned from the method and from the method. + This class implements and . Instances of this class are returned from the method and from the method. ## Examples diff --git a/xml/System.Data.Services.Client/DataServiceCollection`1.xml b/xml/System.Data.Services.Client/DataServiceCollection`1.xml index f786d3a9367..b3dbb794b13 100644 --- a/xml/System.Data.Services.Client/DataServiceCollection`1.xml +++ b/xml/System.Data.Services.Client/DataServiceCollection`1.xml @@ -403,7 +403,7 @@ ## Remarks The property returns a link that is used to access the next set of paged results when paging is enabled in the data service. For more information, see [Configuring the Data Service](/dotnet/framework/data/wcf/configuring-the-data-service-wcf-data-services). - When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. + When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 7108c851106..fc74e32c525 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -2320,7 +2320,7 @@ In such cases, the GUID that is used to register the overload, which is considerably slower than the other overloads. See the overload page for details. + The `WriteEvent` method provides overloads with combinations of string and integer arguments. If none of these combinations match the parameters for the call, the compiler uses the overload, which is considerably slower than the other overloads. See the overload page for details. In all cases, the `eventid` parameter should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index 70ac9a0bf30..143ed8bbbf5 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -764,7 +764,7 @@ The following example checks whether the `type` parameter is valid. If `type` is By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 5a44c4f9292..28b3b7abcfd 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -913,7 +913,7 @@ The following .NET Framework application configuration file example shows the us method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. + The values of the `source`, `eventType`, and `id` parameters are written as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] > The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index 6d8eb78d45c..4c9581f1c0d 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -893,7 +893,7 @@ You can create an object in y method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index a87926b6641..22fbc5c1356 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -1172,7 +1172,7 @@ You can refer to the trace source by using the `name` attribute in the configura The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. - The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. + The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -1359,7 +1359,7 @@ You can refer to the trace source by using the `name` attribute in the configura The method provides an informational message intended to be read by users and not by tools. - calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. + calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. ]]> diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index 8fccdf4758d..3569982eb4c 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -794,7 +794,7 @@ You can create an in your code. method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. diff --git a/xml/System.Drawing.Drawing2D/GraphicsPath.xml b/xml/System.Drawing.Drawing2D/GraphicsPath.xml index eb094ea8ad5..1d8c3c62944 100644 --- a/xml/System.Drawing.Drawing2D/GraphicsPath.xml +++ b/xml/System.Drawing.Drawing2D/GraphicsPath.xml @@ -1049,7 +1049,7 @@ ## Examples For an example see: - + ]]> @@ -1200,7 +1200,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1261,7 +1261,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1461,7 +1461,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1595,7 +1595,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1656,7 +1656,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1780,7 +1780,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -1833,7 +1833,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2027,7 +2027,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -2609,7 +2609,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -3075,7 +3075,7 @@ ## Examples - For an example, see . + For an example, see . ]]> @@ -3397,7 +3397,7 @@ . + For an example, see . ]]> @@ -6098,7 +6098,7 @@ . + For an example, see . ]]> @@ -6162,7 +6162,7 @@ . + For an example, see . ]]> @@ -6228,7 +6228,7 @@ . + For an example, see . ]]> diff --git a/xml/System.Drawing.Drawing2D/Matrix.xml b/xml/System.Drawing.Drawing2D/Matrix.xml index 5c262314468..8daff66beba 100644 --- a/xml/System.Drawing.Drawing2D/Matrix.xml +++ b/xml/System.Drawing.Drawing2D/Matrix.xml @@ -1573,7 +1573,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> @@ -1794,7 +1794,7 @@ Matrix myMatrix = new Matrix(3, 5, 1, 2, 2, 4); . + For an example, see . ]]> diff --git a/xml/System.Drawing.Imaging/ImageAttributes.xml b/xml/System.Drawing.Imaging/ImageAttributes.xml index e05bb6f0713..14ac44803f9 100644 --- a/xml/System.Drawing.Imaging/ImageAttributes.xml +++ b/xml/System.Drawing.Imaging/ImageAttributes.xml @@ -2793,7 +2793,7 @@ ## Examples - For a code example, see the method. + For a code example, see the method. ]]> diff --git a/xml/System.Drawing/Graphics.xml b/xml/System.Drawing/Graphics.xml index 1f391586207..25ecac41527 100644 --- a/xml/System.Drawing/Graphics.xml +++ b/xml/System.Drawing/Graphics.xml @@ -8279,7 +8279,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see . @@ -8383,7 +8383,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see . @@ -8453,7 +8453,7 @@ The object has a transform applied othe , see . + For information about how to draw a , see .